Skip to main content
Back to Skills

Sentry Workflow

Sentry error tracking workflow — setup, source maps, session replay, release management, and alert configuration. Use when integrating Sentry into a project, debugging production errors, or configuring monitoring. Sentry is a Locked Decision for error tracking.

Sentry Workflow

Production error tracking and monitoring patterns for Framework projects. Sentry is a Locked Decision — do not substitute with manual error tracking, LogRocket, or Datadog RUM.

Setup

Next.js Integration

Use the official @sentry/nextjs package. It instruments both client and server automatically.

pnpm add @sentry/nextjs
npx @sentry/wizard@latest -i nextjs

The wizard creates:

  • sentry.client.config.ts — client-side SDK init
  • sentry.server.config.ts — server-side SDK init
  • sentry.edge.config.ts — edge runtime SDK init
  • instrumentation.ts — Next.js instrumentation hook
  • next.config.ts — Sentry webpack plugin for source maps

Required Environment Variables

SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx
SENTRY_AUTH_TOKEN=sntrys_xxx  # For source map uploads, CI only
SENTRY_ORG=your-org
SENTRY_PROJECT=your-project

Critical: SENTRY_AUTH_TOKEN is for CI/build only. Never ship it to the client.

Source Maps

Source maps are essential — without them, production errors show minified code. The @sentry/nextjs webpack plugin uploads source maps automatically during pnpm build.

Verification

After deploying, trigger a test error and check Sentry:

  1. Stack trace should show original TypeScript source (not compiled JS)
  2. File paths should match your repo structure
  3. Line numbers should be accurate

If source maps are broken, check:

  • SENTRY_AUTH_TOKEN is set in CI environment
  • sentry.properties has correct org/project
  • Build output includes .map files

Error Boundaries

Global Error Boundary

// app/global-error.tsx
"use client";
import * as Sentry from "@sentry/nextjs";
import { useEffect } from "react";

export default function GlobalError({ error, reset }: { error: Error; reset: () => void }) {
  useEffect(() => { Sentry.captureException(error); }, [error]);
  return (
    <html><body>
      <h2>Something went wrong</h2>
      <button onClick={reset}>Try again</button>
    </body></html>
  );
}

Route Error Boundaries

Each route segment can have its own error.tsx for granular error handling. Always call Sentry.captureException(error) in the useEffect.

Session Replay

Session Replay records user interactions leading up to an error. Enable it for production debugging.

// sentry.client.config.ts
Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  integrations: [
    Sentry.replayIntegration({
      maskAllText: false,  // Adjust for PII requirements
      blockAllMedia: false,
    }),
  ],
  replaysSessionSampleRate: 0.1,  // 10% of sessions
  replaysOnErrorSampleRate: 1.0,  // 100% of sessions with errors
});

Cost consideration: Replay events count toward your Sentry quota. Start with low session sample rate (0.1) and 100% error sample rate.

Structured Context

Add context to errors so they're actionable, not just stack traces.

// Set user context after auth
Sentry.setUser({ id: user.id, email: user.email });

// Add breadcrumbs for key actions
Sentry.addBreadcrumb({
  category: "payment",
  message: `Checkout started for plan: ${planId}`,
  level: "info",
});

// Tag errors for filtering
Sentry.setTag("feature", "checkout");
Sentry.setTag("plan", planId);

Release Tracking

Tag each deploy with a release version so Sentry can track regressions.

// sentry.client.config.ts
Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  release: process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA,
  environment: process.env.NEXT_PUBLIC_VERCEL_ENV || "development",
});

This enables:

  • Release health — crash-free session rate per deploy
  • Regression detection — new errors introduced by a specific commit
  • Suspect commits — Sentry links errors to the commit that introduced them

Alert Rules

Configure in Sentry Dashboard > Alerts:

Alert Condition Action
New issue First occurrence of an error Slack notification
Regression Previously resolved error reappears Slack + email
Spike Error count > 10x normal in 1h Slack + PagerDuty
Performance p95 transaction time > 3s Slack notification

What NOT to Send to Sentry

  • Expected errors — 404s, validation errors, auth redirects. Filter these:
    Sentry.init({
  beforeSend(event) {
    if (event.exception?.values?.[0]?.type === "NotFoundError") return null;
    return event;
  },
});
  • PII without consent — Don't capture form data, passwords, tokens
  • High-volume debug logs — Use Axiom for structured logging (Locked Decision)

Relationship to Other Tools

  • Sentry = error tracking, crash reporting, session replay (client + server errors)
  • Axiom = structured logging, audit trails, observability (Locked Decision for logging)
  • PostHog = product analytics, feature flags, user behavior (Locked Decision for analytics)

These are complementary, not overlapping. Sentry catches what broke, Axiom records what happened, PostHog tracks what users did.

Search Framework Explorer

Search agents, skills, and standards