# Setting up Sentry

> Configure the built-in Sentry monitoring provider.

*Canonical: https://makerkit.dev/docs/nextjs-prisma/monitoring/sentry*

---

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

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

Optional:

```bash
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