# 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