6.9 KiB
6.9 KiB
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:
- User ID in participant metadata
- User ID in room metadata
- No user ID found
- Multiple user ID formats
- 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
- Use detailed logging during development
- Save snapshots for complex debugging scenarios
- Monitor metadata in real-time for dynamic rooms
- Check both participant and room metadata
- 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
vsuser_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