Kordant/tasks/web-production/10-error-tracking.md

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