CLAUDE.md for Sentry Error Monitoring

Why Sentry Needs Integration Rules

Sentry is the most popular error monitoring platform — but AI assistants use console.error for all error handling, never capture errors with Sentry, and skip the configuration that makes Sentry useful: breadcrumbs, user context, release tracking, and performance monitoring. A Sentry integration without context is just a list of stack traces — you can't reproduce, triage, or prioritize without knowing who was affected, what they were doing, and which release introduced the bug.

The most common AI failures: initializing Sentry without a DSN (no errors captured), not uploading source maps (stack traces show minified code), no user context (you know there's an error but not who hit it), no breadcrumbs (you know the error but not what led to it), and catching errors with try/catch without re-throwing to Sentry.

These rules target Sentry's JavaScript SDK (@sentry/nextjs, @sentry/react, @sentry/node) but the patterns apply to any language SDK.

Rule 1: Proper SDK Initialization

The rule: 'Initialize Sentry as early as possible — before any other code runs. For Next.js: sentry.client.config.ts and sentry.server.config.ts (auto-loaded by @sentry/nextjs). For React: in main.tsx before ReactDOM.render. Configure: dsn (required), environment (production/staging/dev), release (git SHA or version), tracesSampleRate (0.1-1.0 for performance), replaysSessionSampleRate (0.1 for session replay).'

For environment separation: 'Set environment: process.env.NODE_ENV. This separates errors by environment in Sentry's dashboard — production errors get alerts, staging errors are for debugging, dev errors are noise. Never send dev errors to the same Sentry project as production — use separate DSNs or filter by environment.'

AI initializes Sentry without dsn (nothing captured), without release (can't track which deploy introduced the error), and without environment (production and dev errors mixed). One config object with 5 fields makes Sentry useful instead of decorative.

• Initialize before any other code — sentry.client.config.ts for Next.js
• dsn: required — environment: production/staging — release: git SHA
• tracesSampleRate: 0.1-1.0 for performance — replaysSessionSampleRate: 0.1 for replay
• Separate environments — never mix dev and production errors
• beforeSend callback to filter/modify events before sending

Rule 2: Error Capture Patterns

The rule: 'Unhandled errors are captured automatically by Sentry's global handlers. For handled errors (try/catch), capture explicitly: catch (error) { Sentry.captureException(error); throw error; // re-throw if needed }. For React: use Sentry.ErrorBoundary as a component wrapper. For API routes: capture in error middleware. Never swallow errors with empty catch blocks — if you catch it, report it.'

For React error boundaries: '<Sentry.ErrorBoundary fallback={<ErrorFallback />} showDialog={true}>. The ErrorBoundary captures render errors, shows a fallback UI, and optionally shows a user feedback dialog. Wrap the root of your app and individual feature sections for granular error isolation.'

For messages and events: 'Use Sentry.captureMessage for non-error events you want to track: unusual user behavior, deprecation warnings, feature flag activations. Use severity levels: Sentry.captureMessage("User hit deprecated endpoint", "warning"). Messages appear alongside errors in the Sentry dashboard — useful for context without being errors.'

Rule 3: User Context and Breadcrumbs

The rule: 'Set user context on login: Sentry.setUser({ id: user.id, email: user.email, ip_address: "{{auto}}" }). Clear on logout: Sentry.setUser(null). This attaches the user to every error — you know who was affected, can contact them, and can reproduce their exact scenario. Never include passwords or sensitive PII in Sentry context.'

For breadcrumbs: 'Sentry auto-captures: console logs, XHR/fetch requests, DOM clicks, and navigation. Add custom breadcrumbs for business context: Sentry.addBreadcrumb({ category: "checkout", message: "Added item to cart", data: { productId, quantity }, level: "info" }). Breadcrumbs create a timeline of events leading to the error — the most valuable debugging context.'

For tags: 'Add tags for filtering: Sentry.setTag("feature", "checkout"), Sentry.setTag("plan", "enterprise"). Tags are indexed — you can filter the error list by tag. Use for: feature area, user plan, A/B test variant, region, and any dimension you'd filter by in the dashboard.'

• Sentry.setUser({ id, email }) on login — Sentry.setUser(null) on logout
• Auto breadcrumbs: console, fetch, clicks, navigation — already captured
• Custom breadcrumbs: Sentry.addBreadcrumb({ category, message, data })
• Tags for filtering: feature, plan, region — indexed, searchable in dashboard
• Never sensitive PII in context — no passwords, no full card numbers

Rule 4: Performance Monitoring and Tracing

The rule: 'Enable performance monitoring: tracesSampleRate: 0.2 (20% of transactions). Sentry auto-instruments: page loads, API requests, database queries (with ORM integration). Create custom spans for important operations: const span = Sentry.startInactiveSpan({ name: "process-payment" }); ... span.end(). This creates a distributed trace showing where time is spent.'

For web vitals: 'Sentry captures Core Web Vitals automatically: LCP (Largest Contentful Paint), FID (First Input Delay), CLS (Cumulative Layout Shift). View in the Performance dashboard. Set performance alerts: LCP > 2.5s triggers an alert. Use Sentry's data to identify: which pages are slow, which API calls take longest, and which database queries need optimization.'

For sampling: 'tracesSampleRate: 1.0 in development (capture everything), 0.1-0.2 in production (10-20% — enough for trends without overwhelming volume). Use tracesSampler for dynamic sampling: sample 100% of errors, 10% of successful transactions, and 50% of slow transactions.'

Rule 5: Source Maps and Release Tracking

The rule: 'Upload source maps in your build pipeline: npx sentry-cli sourcemaps inject --release=VERSION ./dist && npx sentry-cli sourcemaps upload --release=VERSION ./dist. Or use the build plugin: @sentry/webpack-plugin, @sentry/vite-plugin, withSentryConfig (Next.js). Without source maps, stack traces show minified code — unreadable and undebuggable.'

For releases: 'Tag each deploy with a release: release: process.env.SENTRY_RELEASE or the git SHA. Sentry tracks: errors per release, regression detection (new errors in this release), and deploy tracking. Use sentry-cli releases to associate commits: sentry-cli releases set-commits VERSION --auto. This links errors to the commit that caused them.'

For alerts: 'Configure alerts in Sentry: new error in release → Slack notification. Error rate spike → PagerDuty. P95 latency increase → email. Don't rely on checking the dashboard — push alerts to where your team communicates. Use alert rules to filter noise: only alert on production, only for high-severity, only for error count > threshold.'

• Source maps uploaded in build pipeline — minified traces are useless
• release: git SHA — tracks errors per deploy, regression detection
• set-commits --auto: links errors to the commit that caused them
• Alerts: new error → Slack, rate spike → PagerDuty, latency → email
• Filter alert noise: production only, high severity, count > threshold

Complete Sentry Rules Template

Consolidated rules for Sentry error monitoring integration.

• Initialize earliest: dsn, environment, release, tracesSampleRate — before any code
• Auto-capture + explicit: Sentry.captureException in catch, ErrorBoundary for React
• User context: setUser on login, clear on logout — never sensitive PII
• Breadcrumbs: auto (console, fetch, clicks) + custom (business events)
• Tags for filtering: feature, plan, region — indexed in dashboard
• Performance: tracesSampleRate 0.1-0.2 — web vitals — custom spans for key operations
• Source maps: upload in build — release tracking with git commits
• Alerts: push to Slack/PagerDuty — filter: production, high severity, count threshold