Setting up Sentry

Configure the built-in Sentry monitoring provider.

Sentry is the only built-in monitoring provider in this repo.

Repo Structure

The integration is split across packages:

  • packages/monitoring/api selects and loads the active provider
  • packages/monitoring/sentry contains the Sentry service and the browser/server init configs
  • apps/web/instrumentation.ts runs server register() + onRequestError
  • apps/web/instrumentation-client.ts runs the client instrumentation

This repo does not configure Sentry by wrapping apps/web/next.config.ts with withSentryConfig().

Initialization Flow

Init is owned by the monitoring instrumentation entries, not by SentryMonitoringService:

  • Client — apps/web/instrumentation-client.ts → registerClientMonitoringInstrumentation() installs window.onerror / unhandledrejection handlers and lazy-imports initializeSentryBrowserClient. Errors fired before the Sentry chunk loads are buffered and replayed.
  • Server — apps/web/instrumentation.ts → registerMonitoringInstrumentation() calls initializeSentryServerClient. onRequestError forwards to Sentry's captureRequestError, which records the route, method, and headers.

Sentry's GlobalHandlers integration is filtered out of initializeSentryBrowserClient so the monitoring layer owns global error handling — keeping both would double-report.

Required Environment Variables

NEXT_PUBLIC_MONITORING_PROVIDER=sentry
NEXT_PUBLIC_SENTRY_DSN=https://your-dsn@sentry.io/project-id

Optional:

NEXT_PUBLIC_SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=1.0.0

Key Files

  • apps/web/instrumentation.ts
  • apps/web/instrumentation-client.ts
  • packages/monitoring/api/src/instrumentation.ts
  • packages/monitoring/api/src/instrumentation-client.ts
  • packages/monitoring/api/src/components/provider.tsx
  • packages/monitoring/api/src/server.ts
  • packages/monitoring/sentry/src/sentry.client.config.ts
  • packages/monitoring/sentry/src/sentry.server.config.ts
  • packages/monitoring/sentry/src/services/sentry-monitoring.service.ts

Runtime Behavior

  • client code gets a Sentry-backed monitoring context through MonitoringProvider
  • server code gets a Sentry-backed service through getServerMonitoringService()
  • global window.onerror / unhandledrejection events flow through the monitoring instrumentation, not Sentry's GlobalHandlers
  • server request errors flow through onRequestError → Sentry captureRequestError with full route context
  • client error.tsx skips reporting when error.digest is set, since the error already fired server-side via onRequestError
  • if no provider is configured, monitoring falls back to the console service