broswer-automation/METADATA_LOGGING_GUIDE.md

Metadata Logging Guide for LiveKit Agent

This guide explains how to use the comprehensive metadata logging system to debug and monitor user ID detection in LiveKit rooms.

🎯 Overview

The metadata logging system provides detailed insights into:

• Room metadata content and structure
• Participant metadata for all connected users
• User ID detection results with source tracking
• Comprehensive debugging information

📋 Features

1. Comprehensive Room Analysis

• Complete room metadata inspection
• Participant count and details
• Metadata parsing with error handling
• User ID field detection across multiple formats

2. Detailed Participant Logging

• Individual participant metadata analysis
• Track publication information
• Identity and connection details
• Metadata validation and parsing

3. User ID Search Results

• Priority-based user ID detection
• Source tracking (participant vs room metadata)
• Field name detection (userId, user_id, userID, etc.)
• Comprehensive search reporting

4. Debug Utilities

• Metadata snapshot saving
• Real-time metadata monitoring
• JSON validation and error reporting
• Historical metadata tracking

🚀 Quick Start

Basic Usage

from metadata_logger import log_metadata

# Quick comprehensive logging
search_results = log_metadata(room, detailed=True, save_snapshot=False)

if search_results["found"]:
    print(f"User ID: {search_results['user_id']}")
    print(f"Source: {search_results['source']}")

Advanced Usage

from metadata_logger import MetadataLogger

# Create logger instance
logger = MetadataLogger()

# Detailed room analysis
logger.log_room_metadata(room, detailed=True)

# Extract user ID with detailed results
search_results = logger.extract_user_id_from_metadata(room)
logger.log_metadata_search_results(room, search_results)

# Save snapshot for later analysis
logger.save_metadata_snapshot(room, "debug_snapshot.json")

📊 Sample Output

When User ID Found in Metadata:

================================================================================
                           ROOM METADATA ANALYSIS                            
================================================================================
Timestamp: 2024-01-15 14:30:38
Room Name: provider_onboarding_room_SBy4hNBEVZ
Room SID: RM_provider_onboarding_room_SBy4hNBEVZ

❌ NO ROOM METADATA AVAILABLE

👥 PARTICIPANTS: 1 remote participants

--------------------------------------------------------------------------------
                        PARTICIPANTS METADATA ANALYSIS                        
--------------------------------------------------------------------------------

🧑 PARTICIPANT #1
   Identity: chrome_user_participant
   SID: PA_chrome_user_participant
   Name: Chrome Extension User
   📋 METADATA FOUND:
   Raw Metadata: {"userId":"user_1755117838_y76frrhg2258","source":"chrome_extension"}
   Parsed Metadata: {
         "userId": "user_1755117838_y76frrhg2258",
         "source": "chrome_extension"
      }
   🎯 USER ID FOUND: userId = user_1755117838_y76frrhg2258
   📌 source: chrome_extension

🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍
                              METADATA SEARCH RESULTS                              
🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍🔍

Room: provider_onboarding_room_SBy4hNBEVZ
Search completed at: 2024-01-15 14:30:38
✅ USER ID FOUND!
   Source: participant_metadata
   User ID: user_1755117838_y76frrhg2258
   Location: participant_1.userId
   Full Metadata: {
      "userId": "user_1755117838_y76frrhg2258",
      "source": "chrome_extension"
   }

When No User ID Found:

❌ NO USER ID FOUND IN METADATA
   Checked: ['participant_1', 'participant_2', 'room_metadata']
   Participants checked: 2

🔧 Integration with LiveKit Agent

The metadata logger is automatically integrated into the LiveKit agent:

# In livekit_agent.py entrypoint method
if self.metadata_logger:
    # Log comprehensive metadata information
    self.metadata_logger.log_room_metadata(ctx.room, detailed=True)
    
    # Extract user ID with detailed logging
    search_results = self.metadata_logger.extract_user_id_from_metadata(ctx.room)
    self.metadata_logger.log_metadata_search_results(ctx.room, search_results)
    
    if search_results["found"]:
        chrome_user_id = search_results["user_id"]
        user_id_source = "metadata"

🧪 Testing

Run the test script to see all logging scenarios:

cd agent-livekit
python test_metadata_logging.py

This will demonstrate:

1. User ID in participant metadata
2. User ID in room metadata
3. No user ID found
4. Multiple user ID formats
5. Invalid JSON handling

📁 Metadata Snapshots

Save complete metadata snapshots for debugging:

# Save snapshot with timestamp
logger.save_metadata_snapshot(room)

# Save with custom filename
logger.save_metadata_snapshot(room, "debug_session_123.json")

Snapshot format:

{
  "timestamp": "2024-01-15T14:30:38.123456",
  "room": {
    "name": "provider_onboarding_room_SBy4hNBEVZ",
    "sid": "RM_provider_onboarding_room_SBy4hNBEVZ",
    "metadata": null
  },
  "participants": [
    {
      "identity": "chrome_user_participant",
      "sid": "PA_chrome_user_participant",
      "name": "Chrome Extension User",
      "metadata": "{\"userId\":\"user_1755117838_y76frrhg2258\"}"
    }
  ]
}

🔄 Real-time Monitoring

Monitor metadata changes in real-time:

# Monitor every 5 seconds
logger.monitor_metadata_changes(room, interval=5)

🎯 User ID Field Detection

The system automatically detects user IDs in these field formats:

• userId (preferred)
• user_id (snake_case)
• userID (camelCase)
• USER_ID (uppercase)

🚨 Error Handling

The logger gracefully handles:

• Invalid JSON metadata
• Missing metadata fields
• Network connection issues
• Participant disconnections
• Malformed room data

📝 Best Practices

1. Use detailed logging during development
2. Save snapshots for complex debugging scenarios
3. Monitor metadata in real-time for dynamic rooms
4. Check both participant and room metadata
5. Validate JSON before setting metadata

🔍 Troubleshooting

No metadata showing up:

• Check if participants have joined the room
• Verify metadata was set when creating tokens/rooms
• Ensure JSON is valid

User ID not detected:

• Check field name format (userId vs user_id)
• Verify metadata is properly JSON encoded
• Check both participant and room metadata

Logger not working:

• Ensure metadata_logger.py is in the same directory
• Check import statements in livekit_agent.py
• Verify LOCAL_MODULES_AVAILABLE is True