Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,88 @@
# 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.<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`