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**:
```javascript
// In console, type:
window.__DSS_BROWSER_LOGS
```

**Expected Result**:
```javascript
{
  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**:
```javascript
window.__DSS_BROWSER_LOGS.diagnostic()
```

**Expected Result**:
```javascript
{
  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**:
```javascript
window.__DSS_BROWSER_LOGS.errors()
```

**Get Network Activity**:
```javascript
window.__DSS_BROWSER_LOGS.network()
```

**Get All Logs**:
```javascript
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**:
```javascript
window.__DSS_BROWSER_LOGGER.getLogs({
  search: 'config',        // Search term
  level: 'error',          // Filter by level
  limit: 50                // Max results
})
```

**Search by Time Range**:
```javascript
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**:
```javascript
const data = window.__DSS_BROWSER_LOGS.export();
console.log(JSON.stringify(data, null, 2));
```

**Download to File**:
```javascript
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**:
```javascript
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**:
```json
{
  "status": "stored",
  "sessionId": "session-1733456789-xyz123"
}
```

**Retrieve from Server**:
```bash
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.