dss/.dss/BROWSER_LOGGING_README.md

Browser Console Logging System

Overview

Production-ready browser console log forwarding system that captures all console output (log, info, warn, error, debug) from the admin-ui and streams it to the server for monitoring and debugging.

Architecture

Components

1. Client-Side Forwarder (admin-ui/js/utils/console-forwarder.js)

   • Intercepts all console methods
   • Safe circular reference detection using WeakSet
   • Batching: 50 logs or 2-second intervals
   • Retry mechanism: Up to 3 retries with exponential backoff
   • SendBeacon API for reliable page unload logging

2. Server-Side Logger (tools/api/browser_logger.py)

   • FastAPI router endpoint: POST /api/logs/browser
   • Rotating file handler: 10MB max, 5 backups
   • Log location: .dss/logs/browser-logs/browser.log

3. Proxy Configuration (admin-ui/vite.config.js)

   • Vite proxy forwards /api → http://localhost:8002
   • Allows HTTPS frontend to communicate with HTTP backend

Current Status

✅ All components implemented and integrated ✅ API endpoint tested and functional (server.py:259) ✅ Logs directory created: .dss/logs/browser-logs/ ✅ Port configuration: Vite (3456), FastAPI (8002)

Testing

Manual API Test

```bash curl -X POST http://localhost:8002/api/logs/browser
-H "Content-Type: application/json"
-d '{"logs": [{"level": "info", "timestamp": "2025-12-08T15:00:00Z", "message": "Test", "data": []}]}' ```

Expected response: {"status":"ok","count":1}

View Logs

```bash

View all logs

./admin-ui/scripts/dss-logs.sh

View errors only

./admin-ui/scripts/dss-logs.sh error

View warnings and errors

./admin-ui/scripts/dss-logs.sh warn ```

Test Page

Open browser to: https://localhost:3456/test-console-forwarding.html

Optional: Chrome DevTools Protocol

For deep debugging, use the CDP script:

```bash

On server

./admin-ui/scripts/start-chrome-debug.sh

On local machine (SSH tunnel)

ssh -L 9222:localhost:9222 user@server-ip

Then open chrome://inspect in local browser

```

Files Created/Modified

• ✅ admin-ui/js/utils/console-forwarder.js (NEW)
• ✅ tools/api/browser_logger.py (NEW)
• ✅ admin-ui/index.html (MODIFIED - loads forwarder)
• ✅ admin-ui/vite.config.js (MODIFIED - proxy config)
• ✅ tools/api/server.py (MODIFIED - router integration)
• ✅ admin-ui/scripts/start-chrome-debug.sh (NEW)
• ✅ admin-ui/scripts/dss-logs.sh (NEW)
• ✅ admin-ui/test-console-forwarding.html (NEW - test page)

Safety Features

1. Circular Reference Handling: WeakSet-based detection prevents JSON.stringify crashes
2. Infinite Loop Prevention: No console.error in catch blocks of forwarder
3. Batching: Reduces network overhead (2s or 50 logs)
4. Retry Logic: Up to 3 retries with queue management
5. Error Objects: Explicit serialization of Error instances (message, stack, name)
6. Page Unload: SendBeacon ensures logs sent before navigation

Log Format

``` 2025-12-08 12:03:55,678 [INFO] [BROWSER] [2025-12-08T15:05:00Z] Test log message 2025-12-08 12:03:55,678 [ERROR] [BROWSER] [2025-12-08T15:05:01Z] Error description ```

Next Steps

To verify end-to-end functionality:

1. Open https://localhost:3456/ in a browser
2. Check console output in browser DevTools
3. Verify logs appear in .dss/logs/browser-logs/browser.log

Troubleshooting

Logs not appearing

• Check FastAPI server is running: lsof -i :8002
• Check Vite proxy: curl -X POST https://localhost:3456/api/logs/browser -k
• Check forwarder loaded: View source of https://localhost:3456/

Permission errors

• Log directory uses project-local path (.dss/logs/)
• No root/sudo required

References

• Implementation plan: zen_generated.code (can be deleted)
• Expert analysis: Gemini 3 Pro Preview validation