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

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

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