# Phase 02 — Observability **Dauer:** 1-2 Wochen (Wall-Clock — Multi-Agent), ca. 13-17 Personentage Aufwand **Tasks:** 8 **Ziel:** Self-hosted Sentry live, vollständige Sentry-Wiring (API/Worker/Web) inkl. CI-Release-Tagging, OpenTelemetry-Tracing, ESLint-erzwungene Pino-Logger statt `console.*` und ein Prometheus-/Grafana-Stack mit Infrastruktur- und Business-Metriken. Phase liefert die Sichtbarkeit, die für Phase 03 (Skalierung) zwingend ist. ## Warum diese Phase jetzt - Phase 03 (Skalierungs-Refactoring) verändert Hot-Paths (SharedStore, PgBouncer, Read-Write-Split, Outbox). Ohne saubere Telemetry läuft jedes Refactoring blind — Regression-Detection ist nicht möglich. - Sentry-Release-Tagging muss **vor** den großen Refactorings stehen, damit jeder Phase-03-Commit später in Sentry-Release-Tracking auftaucht. - Logging-Migration (`console.*` → Pino) ist Voraussetzung, damit Sentry-Breadcrumbs und OTel-Logs nicht von PII-leaked `console.log`-Calls geflutet werden. - Self-hosted Sentry statt SaaS, weil das DSGVO-Profil und der vorhandene Hetzner-Server mit Coolify das problemlos hergeben — vermeidet US-Cloud-Datenfluss. ## Hetzner-Staging-Kontext Es existiert bereits ein **Hetzner-Server mit Coolify-Deployment** (siehe `../AGENT-INSTRUCTIONS.md` §Regel 6 + `../archive/STAGING-ACCESS.md`). Sentry-Self-Host, Grafana und Prometheus laufen dort als zusätzliche Coolify-Stacks. Die Apps der Boilerplate (api/worker/web) werden über Coolify auf den gleichen Server deployed und reichen ihre Telemetry an die lokalen Sentry-/OTel-/Prom-Endpoints durch — kein Daten-Egress. ## Task-Reihenfolge | Reihenfolge | Task-ID | Datei | Aufwand | Parallelisierbar mit | |---|---|---|---|---| | 1 | #29 | `sentry-selfhost-setup.md` | 3-4d | — (Infra-Voraussetzung für #30/#31/#32) | | 2 | #30 | `sentry-wiring-api-worker.md` | 1d | #31 (touchen unterschiedliche Apps) | | 3 | #31 | `sentry-wiring-web.md` | 1-1.5d | #30 | | 4 | #32 | `sentry-ci-integration.md` | 0.5d | — (braucht #30 + #31 fertig) | | 5 | #33 | `opentelemetry.md` | 2-3d | #34, #36 (unabhängige Files) | | 6 | #34 | `logging-migration.md` | 2.5-3.5d | #33, #36 | | 7 | #35 | `metrics-grafana.md` | 3-4d | #36 | | 8 | #36 | `performance-quickwins.md` | 1-2d | #33, #34, #35 | ## Dependency-Graph (intern) ``` #29 sentry-selfhost ──► #30 wiring-api-worker ─┐ └─► #31 wiring-web ────────┤ ▼ #32 sentry-ci │ ▼ ┌────────────────────┼────────────────────┐ ▼ ▼ ▼ #33 opentelemetry #34 logging-migration #35 metrics-grafana │ │ │ └────────────────────┼────────────────────┘ ▼ #36 performance-quickwins (parallel — nutzt #35 zum Messen) ``` **Praktisch parallelisierbar (Multi-Agent-Setup):** - Agent A fährt #29 (Infra/Compose) — 3-4 Tage Solo. - Sobald #29 grün: Agent B übernimmt #30, Agent C übernimmt #31 (parallel, unterschiedliche Apps). - Agent A schließt mit #32 ab. - Nach #32: Agent A startet #33, Agent B startet #34, Agent C startet #35, Agent D startet #36 — alle vier parallel möglich, da #36 nur Lese-Zugriff auf die Endpoints aus #35 braucht. ## Phase Done-Definition Diese Phase ist `completed` wenn: - [ ] Alle 8 Tasks `completed` in `PROGRESS.md` - [ ] `pnpm lint` (mit aktivierter `no-console`-Rule auf Server-Code), `pnpm typecheck`, `pnpm test` global grün - [ ] Self-hosted Sentry auf Staging-Hetzner erreichbar unter `https://sentry.`, Login + Test-Event von api/worker/web sichtbar - [ ] Sentry-Release-Tag = `$GIT_SHA` für mindestens eine vollständige CI-Pipeline (GitHub Actions UND Gitea Actions) sichtbar - [ ] OTel-Traces aus api/worker erscheinen in Sentry-Performance UND einem optionalen Tempo-/Jaeger-Stack (falls deployed) - [ ] ESLint-`no-console`-Rule blockiert jeden neuen `console.*`-Call in `**/*.server.ts(x)`, `apps/api/src/**`, `apps/worker/src/**`, `packages/**/src/**` — Test via expliziter Verletzung - [ ] `/status` (public) und `/metrics` (token-protected) liefern in API + Worker valide Outputs, Prometheus scraped erfolgreich, mindestens das "Overview"-Grafana-Dashboard zeigt Live-Daten - [ ] Performance-Quickwins gemerged, Vorher/Nachher-Messungen in `docs/observability/performance-baseline.md` festgehalten - [ ] `.env.example` enthält neue Keys (`SENTRY_DSN`, `SENTRY_RELEASE`, `SENTRY_AUTH_TOKEN`, `SENTRY_TRACES_SAMPLE_RATE`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_TRACES_SAMPLER_ARG`, `METRICS_ENABLED`, `METRICS_TOKEN`) - [ ] `gsd-code-reviewer`-Subagent hat alle Phase-02-Commits reviewed; Findings adressiert - [ ] Phase-Summary in dieser README.md ergänzt ## Phase Summary _(Wird nach Abschluss der Phase vom ausführenden Agent ergänzt.)_ ### Lessons Learned _(Wird nach Abschluss ergänzt.)_ ## Verweise - Detail-MD-Template: `../DETAIL-MD-TEMPLATE.md` - Agent-Workflow: `../AGENT-INSTRUCTIONS.md` - Execution-Order: `../00-execution-order.md` - Live-Status: `../PROGRESS.md` - Vorgänger-Phase: `../01-tech-debt-foundation/README.md` - Nachfolger-Phase: `../03-scaling-infrastructure/README.md`