Debug Configuration

Debug Configuration

DevMirror v0.4.81+ includes powerful debug logging capabilities to help diagnose CDP protocol issues and understand how DevMirror captures console output.

When to Use Debug Logging

Debug logging is useful when:

• Error messages are missing context (file/line info)
• Console output isn't being captured correctly
• You need to understand raw CDP protocol data
• Troubleshooting connection issues with Chrome/CEF

Configuration

Add debug settings to your devmirror.config.json:

{
  "outputDir": "./devmirror-logs",
  "mode": "cdp",
  "url": "http://localhost:3000",
  "debug": {
    "enabled": true,
    "logExceptions": true,
    "logConsoleAPI": true,
    "logLogEntries": true,
    "logRawCDP": false,
    "logToFile": true,
    "logToConsole": false
  }
}

Debug Options

Core Settings

Option	Type	Description	Default
enabled	boolean	Master switch for all debug logging	false
logToFile	boolean	Write debug output to current.log	false
logToConsole	boolean	Output debug to terminal where DevMirror runs	true

Event Categories

Option	Type	Description	Use Case
logExceptions	boolean	Log Runtime.exceptionThrown events	Missing error context
logConsoleAPI	boolean	Log Runtime.consoleAPICalled events	Console.log issues
logLogEntries	boolean	Log Log.entryAdded events	Browser warnings
logRawCDP	boolean	Log ALL CDP protocol traffic	Deep debugging

Output Formats

Debug in Terminal

When logToConsole: true (default), debug output appears in the terminal where DevMirror is running:

[0] [2025-09-25T15:20:46.389Z] [DEBUG:CONSOLE] Raw Runtime.consoleAPICalled data
[0] {
[0]   "type": "debug",
[0]   "args": [
[0]     {
[0]       "type": "string",
[0]       "value": "[vite] connecting..."
[0]     }
[0]   ],
[0]   "executionContextId": 7,
[0]   "timestamp": 1758813646389.369
[0] }

Debug in Log File

When logToFile: true, debug output is written to current.log with special prefixes:

[250925T11:36:24.87] [DEBUG] [DEVMIRROR:EXCEPTION] Raw Runtime.exceptionThrown data
                             {
                               "exceptionId": 1,
                               "text": "Uncaught",
                               "lineNumber": 7,
                               "columnNumber": 0,
                               "scriptId": "221",
                               "url": "http://localhost:12358/js/components/TButtonLit.js"
                             }

Debug Message Prefixes

DevMirror uses distinct prefixes to identify debug messages:

• [DEVMIRROR:EXCEPTION] - Exception event data
• [DEVMIRROR:CONSOLE] - Console API call data
• [DEVMIRROR:LOG] - Browser log entry data
• [DEVMIRROR:CDP] - Raw CDP protocol data

These prefixes distinguish DevMirror's debug output from application debug messages like [DEBUG] [vite] connecting...

Common Debugging Scenarios

1. Missing Error Context

If errors appear without file/line info:

{
  "debug": {
    "enabled": true,
    "logExceptions": true,
    "logToFile": true
  }
}

Check the log for [DEVMIRROR:EXCEPTION] entries to see raw CDP data.

2. Console Output Issues

If console.log messages aren't captured:

{
  "debug": {
    "enabled": true,
    "logConsoleAPI": true,
    "logToFile": true
  }
}

Look for [DEVMIRROR:CONSOLE] entries to see what Chrome is sending.

3. Silent Terminal

To debug without cluttering your terminal:

{
  "debug": {
    "enabled": true,
    "logExceptions": true,
    "logConsoleAPI": true,
    "logToFile": true,
    "logToConsole": false
  }
}

All debug output goes only to current.log.

Performance Considerations

• logRawCDP: true generates massive amounts of data - use sparingly
• Debug logging increases log file size significantly
• Consider using logToConsole: false for production environments
• Disable debug logging when not actively troubleshooting

Tips

1. Start with specific categories (logExceptions, logConsoleAPI) before enabling logRawCDP
2. Use tail -f devmirror-logs/current.log to watch debug output in real-time
3. Debug messages are indented for easier reading in log files
4. Check CDP protocol documentation for understanding raw event data

Related Pages

• Troubleshooting - Common issues and solutions
• Configuration Options - All DevMirror settings
• Technical Architecture - How DevMirror works