> ## 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.

# Monitoring and Alerting

> How PensionsPortal.ie monitors application health, errors, and performance across the stack.

PensionsPortal.ie uses a combination of Sentry, Vercel observability, Cloudflare analytics, and structured application logging to provide full-stack visibility.

## Monitoring Stack

<CardGroup cols={2}>
  <Card title="Sentry" icon="bug">
    Error tracking and performance monitoring. EU region (`de.sentry.io`). Captures exceptions, slow transactions, and custom performance spans.
  </Card>

  <Card title="Vercel Analytics" icon="chart-line">
    Request metrics, function invocation times, and cold start frequency via Vercel's built-in dashboard.
  </Card>

  <Card title="Cloudflare Analytics" icon="shield">
    Edge-level traffic, WAF block events, bot scores, and origin error rates.
  </Card>

  <Card title="Pino Structured Logs" icon="list">
    Application-level structured JSON logs via the `pino` library. Logs are available via Vercel log drains.
  </Card>
</CardGroup>

## Health Endpoints

Three health check endpoints provide operational status:

| Endpoint                | Purpose                                       | Expected Response                         |
| ----------------------- | --------------------------------------------- | ----------------------------------------- |
| `GET /api/health/live`  | Liveness probe — is the process running?      | `200 { status: "ok" }`                    |
| `GET /api/health/ready` | Readiness probe — are dependencies available? | `200` if ready, `503` if not              |
| `GET /api/health/db`    | Database connectivity check                   | `200` if connected, `503` if disconnected |

<Note>
  Health endpoints are designed to never expose internal error details. DB connection strings, environment variable names, and stack traces are explicitly excluded from health endpoint responses — verified by automated security tests.
</Note>

## Sentry Configuration

Sentry is initialised on three runtimes:

| Runtime | Config file                 | Coverage                          |
| ------- | --------------------------- | --------------------------------- |
| Server  | `sentry.server.config.ts`   | API routes, server components     |
| Edge    | `sentry.edge.config.ts`     | Middleware, edge routes           |
| Client  | `instrumentation-client.ts` | Browser errors, client components |

Key settings:

* **DSN**: routes to EU Sentry ingest (`o4510862548467712.ingest.de.sentry.io`)
* **Org**: `137th-advisers` / **Project**: `iorp-ii-prod`
* **Trace sample rate**: 1.0 (100% — review for cost optimisation in high-traffic scenarios)
* **Source maps**: uploaded during CI builds via `SENTRY_AUTH_TOKEN`
* **Tunnel route**: `/monitoring` — proxies browser Sentry requests through the Next.js app to bypass ad-blockers

See [Sentry Observability](/security/sentry-observability) for detailed Sentry configuration.

## Vercel Cron Monitors

Vercel Cron job health is automatically monitored via Sentry's `automaticVercelMonitors` webpack plugin. Missed or failed cron executions trigger Sentry alerts.

## Alerting

| Alert Trigger                      | Channel                          | Severity |
| ---------------------------------- | -------------------------------- | -------- |
| Unhandled exception in production  | Sentry → email / Slack           | High     |
| Error rate spike (>5% of requests) | Sentry → email                   | High     |
| DB health endpoint returns 503     | Uptime monitor → PagerDuty/email | Critical |
| Vercel function timeout spike      | Vercel dashboard                 | Medium   |
| WAF block rate spike               | Cloudflare → email               | Medium   |

<Note>
  Configure uptime monitoring for `/api/health/ready` using an external monitor (e.g., Better Uptime, Checkly, or Vercel's own cron-based checks) to receive alerts when the service is unavailable from outside Vercel.
</Note>

## Log Management

Structured logs are emitted via `pino` and `pino-pretty`. In production, logs flow to Vercel's log drain. Sensitive data (PPS numbers, passwords, connection strings) must never appear in logs — this is enforced by code review and the security test suite.

Log retention periods are defined in [Log Retention and Integrity](/operations/log-retention-and-integrity).