thrilltrack-explorer/docs/ERROR_TRACKING.md

# Error Tracking System Documentation

## Overview

The error tracking system provides comprehensive monitoring and debugging capabilities for ThrillWiki. It captures detailed error context including stack traces, user action breadcrumbs, and environment information.

## Features

### 1. Enhanced Error Context

Every error captured includes:
- **Stack Trace**: First 5000 characters of the error stack
- **Breadcrumbs**: Last 10 user actions before the error
- **Environment Context**: Browser/device information at error time
- **Request Metadata**: Endpoint, method, duration, status code
- **User Context**: User ID, session information

### 2. Error Monitoring Dashboard

**Location**: `/admin/error-monitoring`

**Access**: Admin/Moderator with MFA only

**Features**:
- Real-time error list with auto-refresh (30 seconds)
- Filter by date range (1h, 24h, 7d, 30d)
- Filter by error type
- Search by request ID, endpoint, or error message
- Error analytics (total errors, error types, affected users, avg duration)
- Top 5 errors chart

### 3. Error Details Modal

Click any error to view:
- Full request ID (copyable)
- Timestamp
- Endpoint and HTTP method
- Status code and duration
- Full error message
- Stack trace (collapsible)
- Breadcrumb trail with timestamps
- Environment context (formatted JSON)
- Link to user profile (if available)
- Copy error report button

### 4. User-Facing Error IDs

All errors shown to users include a short reference ID (first 8 characters of request UUID):

```
Error occurred
Reference ID: a3f7b2c1
```

Users can provide this ID to support for quick error lookup.

### 5. Error ID Lookup

**Location**: `/admin/error-lookup`

Quick search interface for finding errors by their reference ID. Enter the 8-character ID and get redirected to the full error details.

## How It Works

### Breadcrumb Tracking

Breadcrumbs are automatically captured for:
- **Navigation**: Route changes
- **User Actions**: Button clicks, form submissions
- **API Calls**: Edge function and Supabase calls
- **State Changes**: Important state updates

### Environment Context

Captured automatically on error:
- Viewport dimensions
- Screen resolution
- Browser memory usage (Chrome only)
- Network connection type
- Timezone and language
- Platform information
- Storage availability

### Error Flow

1. **Error Occurs** → Error boundary or catch block
2. **Context Captured** → Breadcrumbs + environment + stack trace
3. **Logged to Database** → `request_metadata` table via RPC function
4. **User Notification** → Toast with error ID
5. **Admin Dashboard** → Real-time visibility

## Database Schema

### request_metadata Table

New columns added:
- `error_stack` (text): Stack trace (max 5000 chars)
- `breadcrumbs` (jsonb): Array of breadcrumb objects
- `environment_context` (jsonb): Browser/device information

### error_summary View

Aggregated error statistics:
- Error type and endpoint
- Occurrence count
- Affected users count
- First and last occurrence timestamps
- Average duration
- Recent request IDs (last 24h)

## Using the System

### For Developers

#### Adding Breadcrumbs

```typescript
import { breadcrumb } from '@/lib/errorBreadcrumbs';

// Navigation (automatic via App.tsx)
breadcrumb.navigation('/parks/123', '/parks');

// User action
breadcrumb.userAction('clicked submit', 'ParkForm', { parkId: '123' });

// API call
breadcrumb.apiCall('/functions/v1/detect-location', 'POST', 200);

// State change
breadcrumb.stateChange('Park data loaded', { parkId: '123' });
```

#### Error Handling with Tracking

```typescript
import { handleError } from '@/lib/errorHandler';
import { trackRequest } from '@/lib/requestTracking';

try {
  const result = await trackRequest(
    { endpoint: '/api/parks', method: 'GET' },
    async (context) => {
      // Your code here
      return data;
    }
  );
} catch (error) {
  handleError(error, {
    action: 'Load park data',
    metadata: { parkId },
  });
}
```

### For Support Staff

#### Finding an Error

1. User reports error with ID: `a3f7b2c1`
2. Go to `/admin/error-lookup`
3. Enter the ID
4. View full error details

#### Analyzing Error Patterns

1. Go to `/admin/error-monitoring`
2. Review analytics cards for trends
3. Check Top 5 Errors chart
4. Filter by time range to see patterns
5. Click any error for full details

## Best Practices

### DO:
- ✅ Always use error boundaries around risky components
- ✅ Add breadcrumbs for important user actions
- ✅ Use `trackRequest` for critical API calls
- ✅ Include context in `handleError` calls
- ✅ Check error monitoring dashboard regularly

### DON'T:
- ❌ Log sensitive data in breadcrumbs
- ❌ Add breadcrumbs in tight loops
- ❌ Ignore error IDs in user reports
- ❌ Skip error context when handling errors
- ❌ Let errors go untracked

## Performance Considerations

- **Error tracking overhead**: < 10ms per request
- **Breadcrumb memory**: Max 10 breadcrumbs retained
- **Stack trace size**: Limited to 5000 characters
- **Database cleanup**: 30-day retention (automatic)
- **Dashboard refresh**: Every 30 seconds

## Troubleshooting

### Error not appearing in dashboard
- Check if error occurred within selected time range
- Verify error type filter settings
- Try clearing search term
- Refresh the dashboard manually

### Missing breadcrumbs
- Breadcrumbs only captured for last 10 actions
- Check if breadcrumb tracking is enabled for that action type
- Verify error occurred after breadcrumbs were added

### Incomplete stack traces
- Stack traces limited to 5000 characters
- Some browsers don't provide full stacks
- Source maps not currently supported

## Limitations

**Not Included**:
- Third-party error tracking (Sentry, Rollbar)
- Session replay functionality
- Source map support for minified code
- Real-time alerting (future enhancement)
- Cross-origin error tracking
- Error rate limiting

## Future Enhancements

- AI-powered error categorization
- Automatic error assignment to team members
- GitHub Issues integration
- Slack/Discord notifications for critical errors
- Real-time WebSocket updates
- Error severity auto-detection
- Error resolution workflow

## Support

For issues with the error tracking system itself:
1. Check console for tracking errors
2. Verify database connectivity
3. Check RLS policies on `request_metadata`
4. Review edge function logs
5. Contact dev team with details

---

Last updated: 2025-11-03
Version: 1.0.0