# 10. Error Tracking & Alerting (Sentry Integration)

meta:
  id: web-production-10
  feature: web-production
  priority: P1
  depends_on: []
  tags: [observability, error-tracking, production]

objective:
- Implement comprehensive error tracking with Sentry to catch and alert on production errors in real-time

deliverables:
- Sentry integration for backend and frontend
- Error alerting rules
- Source maps upload for production builds
- Breadcrumbs for error context

steps:
1. Add Sentry SDK:
   - Install @sentry/node for backend
   - Install @sentry/solid or @sentry/browser for frontend
   - Configure DSN from environment variable
2. Initialize Sentry in backend:
   - Add to web/src/entry-server.tsx or Nitro plugin
   - Capture unhandled exceptions
   - Capture unhandled promise rejections
   - Attach user context (ID, email) when available
3. Initialize Sentry in frontend:
   - Add to web/src/entry-client.tsx
   - Capture JavaScript errors
   - Capture SolidJS component errors via ErrorBoundary
   - Attach release version and environment
4. Configure error alerting:
   - Slack/Discord/PagerDuty integration for P1 errors
   - Email alerts for new error types
   - Digest emails for recurring errors
   - Alert thresholds: >10 errors/minute or >1 unhandled exception
5. Upload source maps:
   - Configure Vite plugin for source map generation
   - Upload maps to Sentry during build
   - Verify error stack traces show original source
6. Add breadcrumbs:
   - Log navigation changes
   - Log API calls with response status
   - Log user actions (clicks, form submissions)

tests:
- Unit: Test Sentry capture in error scenarios
- Integration: Trigger error, verify appears in Sentry
- Alert: Verify alert fires within 1 minute of error

acceptance_criteria:
- 100% of unhandled exceptions captured in Sentry
- All errors include user context, request URL, and environment
- Source maps working → stack traces show original TypeScript
- Alert fired within 60 seconds of first occurrence
- No duplicate alerts for same error (grouping working)
- Error rate dashboard showing trends over time

validation:
- Deploy with intentional bug → error appears in Sentry within 30s
- Check alert channel → notification received
- View error detail → correct file, line number, user context

notes:
- Sentry free tier: 5k errors/month — may need paid plan for scale
- Use Sentry releases to track which deploy introduced errors
- Consider integrating with GitHub for suspect commits