Instructions

When to Use

• Use for structured logs, correlation IDs, client error hygiene.
• Prefer api-handbook for public error JSON shapes.
• Prefer auth-handbook before logging anything near sessions.

Add observability that works with Next.js App Router: logs, errors, and light tracing. Read observability-basics.md first.

1. Correlation: generate or forward x-request-id (or trace id) in Route Handlers and middleware; pass through Server Actions via async context or explicit argument - pick one pattern per app.
2. Structured logs: JSON lines in server runtime; fields from the contract table in the reference - no raw emails, tokens, or secret query strings.
3. Client errors: error.tsx / reporting hook sends sanitized message + stack fingerprint only; pair with error-loading-not-found.
4. PII: log opaque user ids, not names/emails, unless an audited retention policy says otherwise.
5. External APM (optional): if the repo has Sentry/Datadog/etc., initialize server-only SDK in an instrumentation pattern; never ship server DSN in client bundles.
6. Performance signals: log slow thresholds as metric names, not raw SQL with literals.
7. Sampling: high-traffic info logs should be sampleable; errors stay 100% until volume forces otherwise.

Outcomes