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.<staging-domain>, 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