147 lines
6.4 KiB
Markdown
147 lines
6.4 KiB
Markdown
---
|
||
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.
|