> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pensionsportal.ie/llms.txt
> Use this file to discover all available pages before exploring further.

# Sentry Observability

> Sentry error monitoring, performance tracing, and source map configuration for PensionsPortal.ie.

PensionsPortal.ie uses **Sentry** for production error tracking and performance monitoring. Sentry is configured to use the **EU data region** (`de.sentry.io`), ensuring error telemetry stays within the EEA in compliance with GDPR.

## Project Details

| Setting      | Value                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------- |
| Organisation | `137th-advisers`                                                                                  |
| Project      | `iorp-ii-prod`                                                                                    |
| DSN          | `https://71a9742fce52601d1c9b26656f868cb4@o4510862548467712.ingest.de.sentry.io/4510963882721360` |
| Region       | EU (de.sentry.io)                                                                                 |

## Instrumentation Coverage

Sentry instruments three separate runtimes in Next.js:

<Tabs>
  <Tab title="Server">
    **`sentry.server.config.ts`** — initialised for all server-side request handling.

    ```ts theme={null}
    Sentry.init({
      dsn: "...",
      tracesSampleRate: 1,
      enableLogs: true,
      sendDefaultPii: true,
    })
    ```

    Covers: API routes, React Server Components, server actions.
  </Tab>

  <Tab title="Edge">
    **`sentry.edge.config.ts`** — initialised for edge runtime features.

    ```ts theme={null}
    Sentry.init({
      dsn: "...",
      tracesSampleRate: 1,
      enableLogs: true,
      sendDefaultPii: true,
    })
    ```

    Covers: Next.js middleware, edge API routes.
  </Tab>

  <Tab title="Client">
    **`instrumentation-client.ts`** — initialised in the browser.

    Covers: React component errors, browser-side performance traces.
  </Tab>
</Tabs>

## Key Configuration Options

### Trace Sample Rate

```ts theme={null}
tracesSampleRate: 1,  // 100% of transactions
```

All transactions are currently sampled at 100%. In high-traffic production scenarios, consider reducing to 0.1–0.2 and using `tracesSampler` for dynamic sampling based on route or error status.

### PII Handling

```ts theme={null}
sendDefaultPii: true,
```

Auth.js session user IDs are sent with events, enabling Sentry's user context feature. **PPS numbers must never appear in error messages, stack traces, or event metadata.** Sentry's PII scrubbing rules should be configured in the Sentry dashboard to redact any fields matching PPS patterns.

### Log Integration

```ts theme={null}
enableLogs: true,
```

Sentry captures structured log events alongside error events, providing correlated log context for each error occurrence.

## Source Maps

Source maps are uploaded to Sentry during CI builds via `@sentry/nextjs`'s webpack plugin:

```ts theme={null}
// next.config.ts (Sentry plugin options)
widenClientFileUpload: true,
silent: !process.env.CI,
```

This enables readable stack traces in the Sentry UI — showing original TypeScript source lines rather than minified JavaScript.

The `SENTRY_AUTH_TOKEN` environment variable is required in CI for source map upload. It must be a project-scoped, upload-only token — not an organisation admin token.

## Tunnel Route

```ts theme={null}
tunnelRoute: "/monitoring",
```

Browser-to-Sentry requests are proxied through `/monitoring` on the Next.js server. This ensures Sentry error reports are not blocked by browser ad-blockers or privacy extensions.

## Vercel Cron Monitoring

```ts theme={null}
webpack: {
  automaticVercelMonitors: true,
}
```

Sentry automatically creates cron monitors for Vercel Cron jobs. Missed executions or failures trigger Sentry alerts.

## Alerts and Notifications

Configure the following alert rules in the Sentry dashboard:

| Alert                   | Condition                         | Channel           |
| ----------------------- | --------------------------------- | ----------------- |
| New issue               | Any unhandled exception           | Email + Slack     |
| Issue regression        | Previously resolved issue recurs  | Email             |
| Error rate              | >5% of requests in 5 min window   | Email + PagerDuty |
| Performance degradation | P95 latency exceeds SLO threshold | Email             |

## Debug Logging

Sentry's own debug logging is tree-shaken from production builds:

```ts theme={null}
treeshake: {
  removeDebugLogging: true,
}
```

This reduces bundle size and avoids verbose Sentry internal logs in production.