UXDL Docs
Observability

Sentry

Error monitoring, performance tracking, and release health.

Sentry captures errors, crashes, and performance issues in real time. It groups similar errors, shows stack traces with context, and tracks whether releases introduce regressions.

What Sentry provides

FeaturePurpose
Error monitoringUncaught exceptions with full stack trace
Performance monitoringTransaction traces, slow API routes, Web Vitals
Release trackingTie errors to a specific deploy version
Session replayVisual replay of user sessions before a crash (frontend)
AlertsNotify Slack/PagerDuty when error rate spikes

How Sentry fits our stack

Sentry receives data via its SDK directly, or via OpenTelemetry export. Both paths are supported.

Next.js setup

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

The wizard creates sentry.client.config.ts, sentry.server.config.ts, and sentry.edge.config.ts.

typescript
// sentry.client.config.ts
import * as Sentry from "@sentry/nextjs";
 
Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  environment: process.env.NEXT_PUBLIC_APP_ENV,
  tracesSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
});

Node.js backend setup

bash
pnpm add @sentry/node
typescript
import * as Sentry from "@sentry/node";
 
Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.APP_ENV,
  tracesSampleRate: 0.1,
  integrations: [Sentry.httpIntegration(), Sentry.prismaIntegration()],
});
 
// Express error handler — register after routes
app.use(Sentry.expressErrorHandler());

Environment variables

dotenv
# Frontend (public — safe to expose DSN)
NEXT_PUBLIC_SENTRY_DSN=https://xxx@o123.ingest.sentry.io/456
 
# Backend (server-only)
SENTRY_DSN=https://xxx@o123.ingest.sentry.io/789
SENTRY_AUTH_TOKEN=sntrys_...        # For CI release uploads — vault only
SENTRY_ORG=company
SENTRY_PROJECT=backend-api

Use separate Sentry projects per environment (Alpha, Beta, Prod) or use the environment tag to filter.

Release tracking

Upload source maps and associate commits with releases in CI:

yaml
- name: Create Sentry release
  run: |
    npx sentry-cli releases new "$GITHUB_SHA"
    npx sentry-cli releases set-commits "$GITHUB_SHA" --auto
    npx sentry-cli releases finalize "$GITHUB_SHA"
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}

This lets Sentry answer: "Did this error start after the last deploy?"

Capturing context

Add useful context to every error:

typescript
Sentry.setUser({ id: user.id, email: user.email });
Sentry.setTag("workspace.id", workspaceId);
Sentry.addBreadcrumb({ category: "checkout", message: "Payment initiated" });

When to check Sentry

  • After every Production deploy — watch for new issue groups
  • During incidents — filter by release and environment
  • Weekly — review unresolved issues and assign owners

Official documentation