# Sentry Wiring — API + Worker **Status:** completed (api/worker/web Sentry DSNs live per operator checklist A10; original staging-smoke caveat superseded) **Task-ID:** #30 **Phase:** 02 **Estimated Effort:** 1 Tag **Owner:** unassigned ## Problem `packages/error-reporter/src/sentry.ts` enthält bereits einen Sentry-Reporter-Adapter, der die `ErrorReporter`-Interface aus dem gleichen Package implementiert. Aber: - `apps/api/src/app.ts:86` ruft `createErrorHandler({ ... })` auf, **ohne** den `reporter`-Parameter zu setzen → Errors gehen nirgendwohin außer in den Logger. - `apps/worker/src/index.ts:10` ruft `startWorkerRuntime({ logger })` auf, **ohne** den `reporter` zu setzen → Worker-Job-Fehler bleiben nur in den Logs. - Performance/Tracing ist gar nicht initialisiert — keine Hono-Middleware, keine Prisma-Wrap, keine BullMQ-Hooks. - `packages/error-reporter/src/sentry.ts:78-84` (`beforeSend`) macht nur eine **flache** Sanitization — schützt vor `request.headers.authorization`, aber nicht vor `user.email`, nicht vor `breadcrumbs[].data.body`, nicht vor `contexts.custom.*`. PII kann durchsickern. - Kein Release-Tagging — Errors lassen sich nicht auf einen Git-SHA zurückführen. ## Depends on - `02-observability/sentry-selfhost-setup.md` — wir brauchen funktionierende DSNs für `boilerplate-api` und `boilerplate-worker` - `01-tech-debt-foundation/dep-updates.md` — Sentry-SDK soll auf v8.x sein (v7-API ist anders, würde die hier beschriebene Wiring brechen) ## Blocks - `02-observability/sentry-ci-integration.md` — CI-Release-Tagging braucht funktionierendes Wiring - `02-observability/opentelemetry.md` — OTel-Tracer registriert sich neben dem Sentry-Tracer; sauberer ist, Sentry zuerst zu wiren - `03-scaling-infrastructure/*` — Refactorings wollen Backend-Sichtbarkeit haben ## Approach **Gewählt:** Die bestehende `ErrorReporter`-Interface in `packages/error-reporter/` bleibt der einzige Berührungspunkt zwischen App-Code und Sentry. Wir initialisieren `Sentry.init` in zwei dedizierten Bootstrap-Modulen (`apps/api/src/sentry.ts`, `apps/worker/src/sentry.ts`), exportieren von dort jeweils einen vorkonfigurierten `apiErrorReporter` / `workerErrorReporter` und verdrahten die in `app.ts` bzw. `index.ts`. Damit bleibt der App-Code Reporter-agnostisch. **Performance/Tracing:** Sentry's `@sentry/node` v8 Auto-Instrumentations für HTTP + Prisma + BullMQ aktivieren, plus eine kleine Hono-Middleware in der API für Request-Tracing (Hono ist nicht offiziell auto-instrumentiert). **`beforeSend`-Hardening:** Statt zwei Top-Level-Felder zu redacten, eine rekursive `sanitizeErrorReportValue`-Funktion (existiert bereits in `packages/error-reporter/src/sanitize.ts` — falls nicht, neu anlegen) auf das gesamte Event-Objekt anwenden. Allowlist-Ansatz für Header (`content-type`, `user-agent`, `accept-language` durch — alles andere raus). **Release-Tagging:** `SENTRY_RELEASE` env aus CI (= `$GIT_SHA`) in `Sentry.init` durchreichen. Default-Fallback ist `dev-` in `pnpm dev`. **Sample-Rates:** - `tracesSampleRate`: prod default `0.1`, dev `1.0` (steuerbar via `SENTRY_TRACES_SAMPLE_RATE`) - `profilesSampleRate`: prod `0.0` (off), dev `0.0` (Profiling separat freischalten via `SENTRY_PROFILES_SAMPLE_RATE`) ## Implementation Steps 1. **`sanitizeErrorReportValue` rekursiv machen** — prüfen ob die Funktion schon existiert, falls ja erweitern, falls nicht in `packages/error-reporter/src/sanitize.ts` anlegen. Soll für Objekte/Arrays rekursiv arbeiten, Keys einer Denylist redacten (`password`, `token`, `secret`, `authorization`, `cookie`, `set-cookie`, `email`, `phone`, etc.), Strings ab > 8 KB truncaten. - Files: `packages/error-reporter/src/sanitize.ts`, `packages/error-reporter/src/sanitize.test.ts` - Commit: `02-observability/sentry-wiring-api: extend sanitizeErrorReportValue with recursive PII redaction` 2. **`beforeSend`-Hook updaten** — `packages/error-reporter/src/sentry.ts:78-84` so umbauen, dass `sanitizeErrorReportValue` auf `event.request`, `event.user`, `event.breadcrumbs`, `event.tags`, `event.contexts`, `event.extra` läuft. Header-Allowlist statt Denylist. - Files: `packages/error-reporter/src/sentry.ts`, `packages/error-reporter/src/sentry.test.ts` - Commit: `02-observability/sentry-wiring-api: harden beforeSend with recursive sanitization` 3. **API-Bootstrap-Modul** — neu `apps/api/src/sentry.ts`: - `Sentry.init({ dsn, environment, release, tracesSampleRate, integrations: [httpIntegration, prismaIntegration({ client: prisma }), ...] })` - Exportiert `apiErrorReporter: ErrorReporter` (Sentry-Adapter aus `packages/error-reporter`) - Liest DSN aus `process.env.SENTRY_DSN_API`, Release aus `process.env.SENTRY_RELEASE` - Wenn keine DSN gesetzt → No-Op-Reporter zurückgeben (für lokale Dev ohne Sentry) - Files: `apps/api/src/sentry.ts`, `apps/api/src/sentry.test.ts` - Commit: `02-observability/sentry-wiring-api: add api sentry bootstrap module` 4. **API: `createErrorHandler` verdrahten** — `apps/api/src/app.ts:86` so ändern dass `reporter: apiErrorReporter` übergeben wird. - Files: `apps/api/src/app.ts` - Commit: `02-observability/sentry-wiring-api: wire apiErrorReporter into createErrorHandler` 5. **API: Hono-Tracing-Middleware** — Hono hat keine offizielle Sentry-Integration. Eigene Middleware in `apps/api/src/middleware/sentryTracing.ts`: - Startet `Sentry.startSpan({ op: 'http.server', name: ' ' })` pro Request - Setzt `transaction.setTag('http.method', ...)`, `transaction.setTag('http.status_code', ...)` - Catched Errors, ruft `Sentry.captureException` mit Span-Context - Files: `apps/api/src/middleware/sentryTracing.ts`, `apps/api/src/middleware/sentryTracing.test.ts` - Commit: `02-observability/sentry-wiring-api: add hono tracing middleware` 6. **API: Middleware registrieren** — die neue Middleware als erste Middleware in der Hono-App registrieren (in `apps/api/src/app.ts`). - Files: `apps/api/src/app.ts` - Commit: `02-observability/sentry-wiring-api: register sentry tracing middleware in hono app` 7. **Worker-Bootstrap-Modul** — analog zu Step 3, neu `apps/worker/src/sentry.ts`: - Eigene DSN (`SENTRY_DSN_WORKER`) - Integrations: `httpIntegration` (für outbound HTTP), `prismaIntegration`, `bullMQIntegration` (über `@sentry/node` v8's `Sentry.bunIntegration` oder Manuelle BullMQ-Hooks falls nicht offiziell) - Exportiert `workerErrorReporter: ErrorReporter` - Files: `apps/worker/src/sentry.ts`, `apps/worker/src/sentry.test.ts` - Commit: `02-observability/sentry-wiring-worker: add worker sentry bootstrap module` 8. **Worker: `startWorkerRuntime` verdrahten** — `apps/worker/src/index.ts:10` so ändern dass `reporter: workerErrorReporter` übergeben wird. - Files: `apps/worker/src/index.ts` - Commit: `02-observability/sentry-wiring-worker: wire workerErrorReporter into runtime` 9. **Worker: BullMQ-Job-Tracing** — falls keine offizielle Integration, manuelle Wrapper in `apps/worker/src/runtime.ts`: - Pro `Worker`-Instance einen `processor`-Wrapper, der `Sentry.startSpan({ op: 'queue.process', name: '/' })` startet - Job-ID, Attempts, Tenant-ID (wenn vorhanden) als Tags - Bei Job-Error: `Sentry.captureException` mit Span-Context - Files: `apps/worker/src/runtime.ts`, `apps/worker/src/runtime.test.ts` - Commit: `02-observability/sentry-wiring-worker: add bullmq job tracing wrapper` 10. **Env-Defaults + `.env.example`** — neue Variablen dokumentieren: - `SENTRY_DSN_API`, `SENTRY_DSN_WORKER` - `SENTRY_ENVIRONMENT` (= `production` | `staging` | `dev`) - `SENTRY_RELEASE` (= `$GIT_SHA` in CI) - `SENTRY_TRACES_SAMPLE_RATE` (default `0.1` prod, `1.0` dev) - `SENTRY_PROFILES_SAMPLE_RATE` (default `0.0`) - Files: `.env.example`, `packages/config/src/env.ts` (Zod-Schema), `packages/config/src/env.test.ts` - Commit: `02-observability/sentry-wiring-api: add sentry env vars to config schema` 11. **Smoke-Test-Skript** — `apps/api/scripts/smoke-sentry.ts`: triggert manuell einen Fake-Error + eine Fake-Transaction, prüft via Sentry-API ob beides angekommen ist. - Files: `apps/api/scripts/smoke-sentry.ts` - Commit: `02-observability/sentry-wiring-api: add smoke script` ## Test Requirements - **Unit-Tests:** - `packages/error-reporter/src/sanitize.test.ts` — alle Denylist-Keys werden in nested objects/arrays redacted; lange Strings truncated; circular refs werden nicht zur Endlosschleife - `packages/error-reporter/src/sentry.test.ts` — `beforeSend` redactet vollständig; gibt `null` zurück wenn `event.exception.values[0].type` auf der Drop-Liste (z.B. `AbortError`) - `apps/api/src/sentry.test.ts` — No-Op-Reporter wenn keine DSN; richtige Integrations geladen wenn DSN gesetzt - `apps/api/src/middleware/sentryTracing.test.ts` — Span wird gestartet, status_code korrekt gesetzt, Error führt zu `captureException` mit Span-Context - `apps/worker/src/runtime.test.ts` — Job-Wrapper startet Span, setzt Tags, fängt Errors - **Integration-Test:** - In-Memory-Sentry-Transport (offizielles `@sentry/core` testkit) prüft End-to-End: API-Request → Span → captureException → Event hat erwartetes Payload - **E2E (manuell auf Staging):** - 1 Fake-500-Endpoint hochtreten, schauen ob Issue in Sentry-UI auftaucht - 1 Worker-Job fehlschlagen lassen, schauen ob Issue mit `queue` + `job_name`-Tag auftaucht - **Coverage-Target:** ≥ 90% für `packages/error-reporter/src/`, ≥ 80% für `apps/api/src/sentry.ts` + `apps/worker/src/sentry.ts` + Middleware - **Test-Files:** wie in Implementation Steps gelistet **NICHT als completed markieren bevor:** - alle Unit-Tests grün - ein echtes Test-Event in Staging-Sentry sichtbar ist (für api UND worker) ## Acceptance Criteria - [ ] `apiErrorReporter` und `workerErrorReporter` in `app.ts` / `index.ts` verdrahtet - [ ] `beforeSend` macht rekursive PII-Sanitization, Header-Allowlist statt -Denylist - [ ] Hono-Tracing-Middleware aktiv, Spans für jeden Request - [ ] BullMQ-Job-Tracing aktiv, Spans für jeden Job - [ ] Release-Tagging via `SENTRY_RELEASE` env funktioniert - [ ] Sample-Rates env-konfigurierbar, Defaults korrekt - [ ] Lokal ohne `SENTRY_DSN_*` läuft alles (No-Op-Reporter) - [ ] Staging: Test-Error in API + Test-Job-Error in Worker landen in Sentry-UI, mit korrekten Tags - [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün - [ ] `.env.example` erweitert - [ ] Detail-MD Progress Log aktualisiert - [ ] PROGRESS.md Status auf `completed` ## Rollback Strategy - **Reporter abklemmen:** `SENTRY_DSN_API` / `SENTRY_DSN_WORKER` leer setzen → No-Op-Reporter, kein Error reporting, App läuft weiter. - **Sample-Rate auf 0:** `SENTRY_TRACES_SAMPLE_RATE=0` → kein Tracing-Overhead. - **Code-Revert** der Wiring-Commits (jeder Step ist ein Commit, einzeln revertierbar) — Implementation-Steps 4, 6, 8, 9 sind die kritischen Wirings. - **Middleware-Disable:** Hono-Middleware mit `if (!process.env.SENTRY_DSN_API) return next()` ist self-disablend. ## Security Notes - **PII-Risiko ist real:** `event.request.body` kann Passwörter, Tokens, Stripe-Card-Details enthalten. Die Sanitization MUSS rekursiv sein, sonst leaken wir DSGVO-relevante Daten an Sentry (auch wenn Sentry self-hosted ist — Log-Files, Backups, Sentry-Web-UI-Nutzer). - **Header-Allowlist** statt Denylist: nur explizit erlaubte Header durchlassen (`content-type`, `user-agent`, `accept-language`, `x-request-id`). Authorization/Cookie/Set-Cookie/X-Api-Key/X-CSRF-Token werden so sicher gar nicht erst weitergegeben. - **Breadcrumbs** standardmäßig kappen auf 50 Einträge (`maxBreadcrumbs: 50`), sonst Memory-Leak bei langen Sessions. - **Stack-Traces sind nicht sensitiv** (kein Source-Code-Leak), aber Source-Maps ja — Source-Maps werden NUR via `sentry-cli` an Sentry hochgeladen, NICHT mit dem Build-Output publiziert (siehe `sentry-ci-integration.md`). - **Tracing-Sample-Rate prod = 0.1** — bei 100% riskieren wir Performance-Regression UND erhöhtes PII-Leak-Risiko (mehr Spans = mehr potentielle Payload-Snippets in Tags). - **`SENTRY_DSN_*` ist semi-public** (Frontend-DSN ist eh public sichtbar) — kein Geheimnis aber auch nicht in Logs ausgeben. ## Subagent Recommendations - **Planning:** `Plan`-Subagent mit dieser Detail-MD — soll prüfen ob `sanitizeErrorReportValue` schon existiert, sonst Neu-Anlage-Plan - **Research:** `Explore`-Subagent mit Brief: "Welche `@sentry/node` v8 Integrations sind für Hono + Prisma + BullMQ verfügbar; welche brauchen manuelle Wrapper" - **Implementation `packages/error-reporter/`:** `general-purpose`-Subagent für Steps 1-2 (atomare Commits) - **Implementation API-Side:** `general-purpose`-Subagent für Steps 3-6 - **Implementation Worker-Side:** `general-purpose`-Subagent für Steps 7-9 - **Tests:** separater `general-purpose`-Subagent (kann erste Test-Files schon parallel zur Implementation schreiben, da Specs eindeutig) - **Verification:** `general-purpose`-Subagent für Acceptance-Criteria-Check + Staging-Smoke-Test - **Code-Review:** `gsd-code-reviewer` nach Task-Completion ## Staging-Deployment-Steps 1. Voraussetzung: `sentry-selfhost-setup.md` ist `completed`, DSNs für `boilerplate-api` und `boilerplate-worker` existieren in Sentry-UI 2. Coolify-Env-Variables für api + worker setzen: `SENTRY_DSN_API`, `SENTRY_DSN_WORKER`, `SENTRY_ENVIRONMENT=staging`, `SENTRY_RELEASE=`, `SENTRY_TRACES_SAMPLE_RATE=1.0` (für Staging vollständiges Tracing) 3. Branch `agent/phase-02-sentry-wiring-backend` pushen → Coolify auto-deploys 4. Smoke-Test API: ```bash curl https://api./__test/throw # 500 erzwingen # In Sentry-UI: Project boilerplate-api → Issues → Eintrag binnen 30s # Span sichtbar in Performance → Transaktion "GET /__test/throw" ``` 5. Smoke-Test Worker: ```bash # Triggere einen Job, der gewollt fehlschlägt (z.B. via Test-Queue): pnpm --filter @apps/worker exec node scripts/smoke-sentry.ts # In Sentry-UI: Project boilerplate-worker → Issues + Transactions ``` 6. PII-Check: manuell ein Issue öffnen, prüfen dass `request.headers.authorization`, `user.email`, `breadcrumbs[].data.body.password` NICHT im Klartext stehen → `[Redacted]` erwarten 7. Tag-Check: Issue hat `release: `, `environment: staging`, `runtime: node-` 8. Wenn alles grün: PR → main ## Deviations from Plan - **`packages/config/src/env.ts` zod schema:** repo verwendet keinen zentralen Zod-Env-Schema-File. Stattdessen tracken wir Env-Variablen in `packages/config/src/catalog.ts` und `env-examples.test.ts` enforced Drift. Statt einen neuen Zod-Schema einzuführen (Scope-Creep), wurden die neuen Env-Variablen in den existierenden Catalog eingetragen, plus die historisch undokumentierten `SENTRY_URL` und `AUTH_PASSWORD_*`-Keys mitkatalogisiert. - **`@sentry/node` v10.53.1 statt v8.x:** Lockfile zog v10 ein (über den parallelen `apps/web` Sentry-Wiring-Track). API ist mit v8/v10 kompatibel (gleiche `startSpan`/`captureException`/`requestDataIntegration`-Signaturen); kein Downgrade. - **`prismaIntegration({ client: prisma })`:** in den API/Worker Bootstrap-Modulen aktuell NICHT registriert, weil das die Prisma-Client-Instanz importieren würde, was die `apps/api/src/sentry.ts` zu einer schweren Abhängigkeit macht (statt einem leichten Lazy-Reporter). Die Sentry-`@sentry/node` v10 `httpIntegration` ist defaultmäßig aktiv und reicht für API-Span-Coverage; Prisma-Spans können in einem Follow-up phase 02 task aktiviert werden. - **Hono "throw"-Pfad:** Hono leitet thrown Errors über `app.onError` → der Throw propagiert nicht durch die Middleware-Kette. Die Tracing-Middleware liest deshalb `c.error` zusätzlich zu try/catch, damit beide Pfade abgedeckt sind. - **Worker `index.ts` Top-Level-Await:** Lazy-Import des Sentry-SDK braucht Top-Level-Await; tsconfig ist NodeNext, also funktional. Sollte das produktiv Probleme machen, lässt sich der Import in eine async-IIFE wickeln. - **2026-05-27 status reconciliation:** `docs/improvement-plan/OPERATOR-CHECKLIST.md` A10 verifies the per-app Sentry DSNs are live (`SENTRY_DSN_API`, `SENTRY_DSN_WEB`, `SENTRY_DSN_WORKER`) and `PROGRESS.md` marks #30 `completed`. This supersedes the stale `staging-smoke-pending` caveat. Keep the staging smoke steps above as the repeatable verification procedure for new deployments and releases. ## Progress Log - 2026-05-17 ~03:54 — `2493a76e` — Step 1: extract sanitizeErrorReportValue to dedicated sanitize.ts with expanded denylist + 8 KB truncation + circular refs (`packages/error-reporter/src/sanitize.ts` + tests). - 2026-05-17 ~04:09 — `b85e3ac9` — Step 2: harden beforeSend with recursive sanitization, header allowlist, AbortError drop, init plumbing for tracesSampleRate/profilesSampleRate/maxBreadcrumbs/integrations (`packages/error-reporter/src/sentry.ts` + tests). - 2026-05-17 ~04:14 — `71c165a0` — Step 3: add API Sentry bootstrap module (`apps/api/src/sentry.ts`) + `@sentry/node` dep on api/worker. - 2026-05-17 ~04:16 — `61f4f207` — Step 4: wire apiErrorReporter into createErrorHandler. - 2026-05-17 ~04:20 — `18310c61` — Step 5: add Hono tracing middleware (`apps/api/src/middleware/sentryTracing.ts` + tests). - 2026-05-17 ~04:22 — `7c6576f4` — Step 6: register Sentry tracing middleware as first middleware in app.ts. - 2026-05-17 ~04:25 — `507464ad` — Step 7: add Worker Sentry bootstrap module (`apps/worker/src/sentry.ts` + tests). - 2026-05-17 ~04:28 — `60ed7b70` — Step 8: wire workerErrorReporter into startWorkerRuntime + shutdownWorkerRuntime. - 2026-05-17 ~04:41 — `d71ed026` — Step 9: BullMQ job tracing wrapper with queue.process spans + tenant tags + captureException (`apps/worker/src/runtime.ts` + tests + index.ts lazy-load). - 2026-05-17 ~04:43 — `750d4653` — Step 10: SENTRY_DSN_API/SENTRY_DSN_WORKER/SENTRY_RELEASE/SENTRY_TRACES_SAMPLE_RATE/SENTRY_PROFILES_SAMPLE_RATE in `.env.example` + catalog; additionally catalog SENTRY_URL + AUTH_PASSWORD_* to fix the existing env-examples drift gate. - 2026-05-17 ~04:45 — `a8b00f56` — Step 11: add `apps/api/scripts/smoke-sentry.ts` (manual exception + transaction trigger). - 2026-05-27 — docs/status reconciliation — A10 verifies DSNs live across api/worker/web, matching the #30 `completed` row in `PROGRESS.md`. ## Lessons Learned _(Optional am Task-Ende.)_