dss/.dss/WORKFLOWS/01-capture-browser-logs.md

Workflow 01: Capture Browser Logs

Purpose: Capture and retrieve all browser-side logs from DSS dashboard for debugging

When to Use:

• User reports dashboard not loading
• JavaScript errors in browser
• Network request failures
• Performance issues
• Configuration problems

Estimated Time: 2-5 minutes

---

Prerequisites

• Dashboard accessible (https://dss.overbits.luz.uy/ or http://localhost:3456/admin-ui/index.html)
• Browser DevTools available (Chrome, Firefox, Edge, Safari)
• Browser logger module loaded (browser-logger.js)

---

Step-by-Step Procedure

Step 1: Open DSS Dashboard

Action:

Navigate to: https://dss.overbits.luz.uy/
Or local: http://localhost:3456/admin-ui/index.html

Expected Result: Dashboard loads (may require credentials)

Troubleshooting:

• If 401 Unauthorized: Provide htpasswd credentials
• If connection refused: Check API server running on port 3456
• If 500 error: Check server logs with journalctl -u dss-api -f

---

Step 2: Open Browser DevTools

Action:

Chrome/Edge: F12 or Cmd+Option+I (Mac) or Ctrl+Shift+I (Windows)
Firefox: F12 or Cmd+Option+K (Mac) or Ctrl+Shift+K (Windows)
Safari: Cmd+Option+C (Mac, requires enabling in Preferences)

Expected Result: DevTools panel opens at bottom or side of browser

Go to Console Tab: Click "Console" in the top menu of DevTools

---

Step 3: Verify Browser Logger is Loaded

Action:

// In console, type:
window.__DSS_BROWSER_LOGS

Expected Result:

{
  all: ƒ (),
  errors: ƒ (),
  network: ƒ (),
  diagnostic: ƒ (),
  export: ƒ (),
  print: ƒ (),
  clear: ƒ ()
}

Troubleshooting:

• If undefined: Browser logger not loaded. Check Network tab for /admin-ui/js/core/browser-logger.js (should be 200 OK)
• If 404 on browser-logger.js: File not imported in index.html
• Manually load: import('/admin-ui/js/core/browser-logger.js').then(() => console.log('Loaded'))

---

Step 4: Get Diagnostic Summary

Action:

window.__DSS_BROWSER_LOGS.diagnostic()

Expected Result:

{
  sessionId: "session-1733456789-xyz123",
  uptime: 45230,                    // ms since page load
  totalLogs: 127,
  errorCount: 3,
  warnCount: 5,
  networkRequests: 12,
  memory: {
    usedJSHeapSize: 15728640,
    jsHeapSizeLimit: 2172649472,
    usagePercent: "0.72"
  },
  url: "https://dss.overbits.luz.uy/",
  userAgent: "Mozilla/5.0...",
  recentErrors: [...],              // Last 5 errors
  recentNetworkRequests: [...]      // Last 5 requests
}

Analysis:

• errorCount > 0: Check recentErrors for critical issues
• networkRequests == 0: No API calls made (possible config issue)
• usagePercent > 80: Memory leak or performance issue

---

Step 5: Retrieve Specific Log Types

Get All Errors:

window.__DSS_BROWSER_LOGS.errors()

Get Network Activity:

window.__DSS_BROWSER_LOGS.network()

Get All Logs:

window.__DSS_BROWSER_LOGS.all()

Expected Result: Array of log entries with timestamps, levels, categories, messages, and data

Analysis Tips:

• Look for level: 'error' entries first
• Check category: 'fetchError' for failed API calls
• Check status: 404 or status: 500 in network logs
• Check category: 'uncaughtError' for JavaScript exceptions

---

Step 6: Search for Specific Issues

Search by Keyword:

window.__DSS_BROWSER_LOGGER.getLogs({
  search: 'config',        // Search term
  level: 'error',          // Filter by level
  limit: 50                // Max results
})

Search by Time Range:

const oneHourAgo = Date.now() - (60 * 60 * 1000);
window.__DSS_BROWSER_LOGGER.getLogs({
  minTime: oneHourAgo,
  limit: 100
})

Expected Result: Filtered log entries matching criteria

---

Step 7: Export Logs for Analysis

Export as JSON:

const data = window.__DSS_BROWSER_LOGS.export();
console.log(JSON.stringify(data, null, 2));

Download to File:

const data = window.__DSS_BROWSER_LOGS.export();
const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'dss-browser-logs-' + Date.now() + '.json';
a.click();

Expected Result:

• JSON export displays in console
• File downloads with name like dss-browser-logs-1733456789000.json

---

Step 8: Send Logs to Server (Optional)

Manual Upload:

const logs = window.__DSS_BROWSER_LOGS.export();
fetch('/api/browser-logs', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(logs)
}).then(r => r.json()).then(console.log);

Expected Result:

{
  "status": "stored",
  "sessionId": "session-1733456789-xyz123"
}

Retrieve from Server:

curl http://localhost:3456/api/browser-logs/session-1733456789-xyz123

---

Common Issues and Solutions

Issue 1: No Logs Captured

Symptoms: totalLogs: 0 or empty arrays

Causes:

• Browser logger loaded after app initialized
• Logger not intercepting console calls
• Storage disabled (private browsing)

Solution:

1. Reload page with DevTools open
2. Check browser-logger.js import order (should be first)
3. Check console for storage errors

---

Issue 2: Logs Not Persisting Across Reloads

Symptoms: Logs disappear on page refresh

Causes:

• sessionStorage disabled
• Private/Incognito mode
• Storage quota exceeded

Solution:

1. Check browser privacy settings
2. Use regular browsing mode
3. Clear old logs: window.__DSS_BROWSER_LOGS.clear()

---

Issue 3: Network Logs Missing

Symptoms: networkRequests: 0 but API calls visible in Network tab

Causes:

• Browser logger loaded after fetch calls
• Using XMLHttpRequest instead of fetch
• API calls made before logger init

Solution:

1. Ensure browser-logger.js is first script loaded
2. Reload page to capture from start
3. Check if app uses XMLHttpRequest (not currently intercepted)

---

Success Criteria

• ✅ Diagnostic shows session info and uptime
• ✅ Logs captured for errors, warnings, network requests
• ✅ Can export logs as JSON
• ✅ Can search and filter logs
• ✅ Memory usage tracked

---

Next Steps

After capturing browser logs:

1. If errors found: Use Workflow 02 (Diagnose Errors)
2. If performance issues: Use Workflow 03 (Debug Performance)
3. If API failures: Check server logs with journalctl -u dss-api -f
4. If configuration issues: Check /api/config endpoint response

---

Related Documentation

• .dss/BROWSER_LOG_CAPTURE_PROCEDURE.md - Detailed browser logger documentation
• .dss/GET_BROWSER_LOGS.sh - Quick reference hook script
• admin-ui/js/core/browser-logger.js - Logger source code
• .dss/MCP_DEBUG_TOOLS_ARCHITECTURE.md - Overall debug architecture

---

MCP Tool Access

From Claude Code:

Use tool: dss_get_browser_diagnostic
Or: dss_get_browser_errors
Or: dss_get_browser_network

These MCP tools automatically retrieve browser logs via the API layer.