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**
```python
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**
```python
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:

```python
# 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:

```bash
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:

```python
# Save snapshot with timestamp
logger.save_metadata_snapshot(room)

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

**Snapshot format:**
```json
{
  "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:

```python
# 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