further rework to the documentation

2025-11-20 12:31:21 +01:00
parent 6afa44d947
commit 9afcaa7836
90 changed files with 1721 additions and 29 deletions
--- a/docs/ops/monitoring-observability.md
+++ b/docs/ops/monitoring-observability.md
@@ -0,0 +1,146 @@
+---
+title: Monitoring & Observability
+sidebar_label: Monitoring
+---
+
+Dieses Dokument sammelt die wichtigsten Monitoring‑Punkte der Plattform und soll helfen, die richtigen Dashboards und Alerts aufzubauen.
+
+## 1. Was sollte überwacht werden?
+
+- **Verfügbarkeit**
+  - HTTP‑Checks auf zentrale Endpunkte (Landing, Join‑Token‑Flows, Guest Upload, Tenant Admin Login).
+  - Public‑API‑Checks (`/api/v1/events/{token}`, Galerie, Upload‑Endpoints).
+- **Queues**
+  - Länge und Durchsatz der Queues `default`, `media-storage`, `media-security`, `notifications`.
+  - Age/Time‑in‑Queue, Anzahl der Failed Jobs.
+- **Storage**
+  - Füllstand der Hot‑Storage‑Volumes/Buckets.
+  - Anzahlen/Status in `event_media_assets` (z.B. viele `pending` oder `failed`).
+- **Fehler-Raten**
+  - HTTP 5xx/4xx spitzenweise, gruppiert nach Route/Service.
+  - Applikations‑Logs mit Error/Warning‑Level.
+- **Billing & Webhooks**
+  - Fehlgeschlagene Paddle/RevenueCat‑Webhooks.
+  - Differenz zwischen erwarteten und verarbeiteten Zahlungen (optional).
+
+## 2. Werkzeuge & Quellen
+
+- **Horizon**
+  - Live‑Überblick über Laravel‑Queues.
+  - Alerts, wenn eine Queue zu lange Backlog aufbaut.
+- **Docker/Dokploy**
+  - Container‑Health (Restart‑Loops, Ressourcennutzung).
+  - Service‑Healthchecks.
+- **Logs**
+  - Laravel‑Logs (`storage/logs/*.log`), ggf. via Promtail/Loki oder ELK zentralisiert.
+  - Spezifische Channels (z.B. `storage-jobs`, `notifications`, `billing`).
+- **Metriken**
+  - Falls vorhanden: Prometheus/Grafana‑Dashboards für App‑/DB‑/Redis‑Metriken.
+
+> TODO: Wenn konkrete Dashboards in Grafana o.Ä. existieren, füge hier Screenshots/Links und eine kurze Erklärung der Panels ein.
+
+## 3. Alarmierung & Schwellenwerte
+
+Konkrete Schwellenwerte hängen von Traffic und Infrastruktur ab, aber folgende Muster haben sich bewährt:
+
+- **Queues**
+  - `default`:
+    - Warnung: > 100 Jobs oder ältester Job > 5 Minuten.
+    - Kritisch: > 300 Jobs oder ältester Job > 15 Minuten.
+  - `media-storage`:
+    - Warnung: > 200 Jobs oder ältester Job > 10 Minuten.
+    - Kritisch: > 500 Jobs oder ältester Job > 30 Minuten.
+  - `media-security`:
+    - Warnung: > 50 Jobs oder ältester Job > 5 Minuten.
+    - Kritisch: > 150 Jobs oder ältester Job > 15 Minuten.
+  - `notifications`:
+    - Warnung: > 100 Jobs dauerhaft im Backlog.
+    - Kritisch: wenn die Queue dauerhaft wächst, während Events live laufen.
+- **Uploads**
+  - Fehlerquote bei Upload‑Endpoints:
+    - Warnung: 2–5 % Fehler (HTTP 4xx/5xx) über 5‑minütiges Fenster.
+    - Kritisch: > 5–10 % Fehler in 5 Minuten.
+  - Anzahl „hängender“ Uploads:
+    - Warnung, wenn `storage:check-upload-queues` für denselben Event wiederholt Alarm schlägt (z.B. mehr als 5 benachrichtigte Events in 10 Minuten).
+- **Public API**
+  - Latenz für `GET /api/v1/events/{token}` und `/photos`:
+    - Warnung: P95 > 500 ms über 5 Minuten.
+    - Kritisch: P95 > 1–2 s über 5 Minuten.
+  - Fehlerraten für diese Endpoints:
+    - Warnung: > 2 % 5xx über 5 Minuten.
+    - Kritisch: > 5 % 5xx über 5 Minuten.
+- **Billing**
+  - Failed Webhooks:
+    - Warnung: mehr als N (z.B. 5–10) fehlgeschlagene Webhooks pro 10 Minuten.
+    - Kritisch: schneller Anstieg oder > 20 % Fehleranteil.
+  - Differenz zwischen erwarteten und verarbeiteten Zahlungen:
+    - Regelmäßige Reports (z.B. täglich) statt harter Alerts, aber auffällige Abweichungen sollten ein Incident auslösen.
+
+## 4. Betriebliche Nutzung
+
+- **Daily Checks**
+  - Horizon Queue‑Dashboard kurz prüfen.
+  - Logs auf neue Fehler‑/Warnmuster scannen.
+- **Bei Incidents**
+  - Monitoring‑Daten helfen, Ursache und zeitlichen Verlauf zu rekonstruieren (siehe `docs/ops/incidents-major.md`).
+
+## 5. Zusammenspiel mit bestehenden Kommandos
+
+Einige Artisan‑Kommandos sind explizit für Monitoring/Health gedacht. Sie sollten in Cron/Scheduler oder externe Checks integriert werden:
+
+- `storage:monitor` (falls vorhanden)
+  - Aggregiert Storage‑Auslastung und Queue‑Health basierend auf `config/storage-monitor.php`.
+  - Kann Alerts per Mail/Log triggern, wenn Schwellwerte überschritten werden.
+- `storage:check-upload-queues`
+  - Überprüft, ob Upload‑bezogene Queues im erwarteten Rahmen liegen und triggert Gast‑Alerts bei Problemen (siehe `docs/ops/guest-notification-ops.md`).
+- `storage:archive-pending`
+  - Kein klassisches Monitoring‑Kommando, aber relevant, um zu prüfen, ob Archivierungsjobs hinterherhinken (z.B. viele alte `hot`‑Assets).
+
+Diese Kommandos sind kein Ersatz für echtes Monitoring, liefern aber wertvolle Signale, die in Dashboards und Alerts einfließen können.
+
+## 6. Beispiele für Metrik- und Alert-Definitionen
+
+Nachfolgend beispielhafte Formulierungen, wie Alerts unabhängig vom verwendeten Monitoring‑System aussehen könnten.
+
+### 6.1 Queue-Backlog Alert (Pseudocode)
+
+**Ziel**: Meldung, wenn `media-storage` zu lange Backlog aufbaut.
+
+- Bedingung:
+  - `queue_length("media-storage") > 500` **OR**
+  - `oldest_job_age("media-storage") > 30min`
+- Dauer:
+  - 2 aufeinanderfolgende Messintervalle (z.B. 2×5 Minuten).
+- Aktion:
+  - Alarm an On‑Call + Hinweis auf `docs/ops/media-storage-spec.md` und `docs/ops/dr-storage-issues.md`.
+
+### 6.2 Upload-Error-Rate Alert
+
+**Ziel**: Upload‑Probleme für Gäste früh erkennen.
+
+- Bedingung:
+  - Anteil `5xx` oder „applikationsspezifische Fehlercodes“ bei `POST /api/v1/events/*/upload` > 5 % in 5 Minuten.
+- Aktion:
+  - Alarm an On‑Call, Link zum Public‑API‑Incident‑Playbook und Storage‑Runbook.
+
+### 6.3 Public-API-Latenz Alert
+
+**Ziel**: Langsame Galerien / Token‑Aufrufe frühzeitig sehen.
+
+- Bedingung:
+  - `P95(latency(GET /api/v1/events/*)) > 1000ms` über 5 Minuten.
+- Aktion:
+  - Alarm an On‑Call, eventuell automatische Skalierung oder Untersuchung (DB/Redis‑Last).
+
+### 6.4 Billing-Webhook Alert
+
+**Ziel**: Fehler bei Paddle/RevenueCat‑Webhook‑Verarbeitung erkennen.
+
+- Bedingung:
+  - Mehr als 10 fehlgeschlagene Webhook‑Verarbeitungen innerhalb von 10 Minuten, oder Verhältnis `failed/success` > 0,2.
+- Aktion:
+  - Alarm an On‑Call + Finance/Billing‑Verantwortliche, Verweis auf `docs/ops/billing-ops.md`.
+
+Diese Beispiele sollen helfen, konkrete Regeln in eurem Monitoring‑Tool zu definieren. Die genauen Zahlen sollten anhand realer Traffic‑Muster feinjustiert werden.
+
+Dieses Dokument ist bewusst technologie‑agnostisch formuliert – die konkrete Implementierung (Prometheus, Grafana, Loki, ELK, SaaS‑Monitoring) sollte hier nachgezogen und mit Beispielen ergänzt werden.