---
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.