Monitoring Setup

---
name: monitoring-setup
description: |
  Trigger when the user asks to add monitoring, observability, metrics, or
  error tracking. Phrases: "set up Sentry", "add monitoring", "observability",
  "OpenTelemetry", "add metrics", "error tracking".
allowed-tools:
  - Bash(npm install *)
  - Bash(pnpm add *)
  - Read
  - Write
  - Edit
---

# Monitoring Setup

Add the three-legged observability stack (errors, logs, metrics) with the
minimum viable config. Focus on signals that actually page someone.

## Prerequisites

- Production target identified (Vercel, Coolify, Fly, AWS, etc.)
- Stack known (Node, Python, etc.)

## Steps

1. **Errors first: Sentry.** Most bang for the buck in 24 hours of setup.
   ```bash
   pnpm add @sentry/nextjs
   npx @sentry/wizard@latest -i nextjs
   ```

2. **Set release tracking.** Sentry groups errors by release. Wire the release
   to the git SHA via env var:
   ```
   SENTRY_RELEASE=${VERCEL_GIT_COMMIT_SHA}
   ```

3. **Add one alert that wakes someone.** In Sentry: new-issue alert on
   production. Target: PagerDuty, Slack #oncall, or email.

4. **Logs next: structured JSON to stdout.** Let the platform collect. In Node:
   ```ts
   import { pino } from "pino";
   export const log = pino({ level: "info" });
   ```

   Replace `console.log` with structured log calls:
   ```ts
   log.info({ userId, route }, "user signed in");
   ```

5. **Metrics last: OpenTelemetry for traces, Prometheus scrape for counters.**
   For a small app, skip Prometheus and use OpenTelemetry traces only.
   ```bash
   pnpm add @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node
   ```

6. **Hook up a dashboard.** Honeycomb, Datadog, or Grafana. One dashboard
   with four tiles: error rate, p95 latency, request rate, saturation.

## What not to do

- Do not set up 17 dashboards no one looks at.
- Do not log every request body at info level. PII and volume costs.
- Do not alert on every warning. Alerts that do not wake someone train people
  to ignore alerts.

## Output

- Sentry configured with release + one alert
- Structured logging in place, console.log grepped and migrated
- OpenTelemetry traces to at least one collector
- Dashboard with 4 core tiles