fotospiel-app/docs/ops/monitoring-observability.md

title, sidebar_label

title	sidebar_label
Monitoring & Observability	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.