# Observability: Dashboards & Alerts

Dieses Dokument definiert die Monitoring-Strategie für das Masterdata-SCS gemäß der Roadmap.

## 1. Zentrale Dashboards

### 1.1 Import Performance Dashboard

*Fokus: Überwachung des ZNS-Ingestion-Workers.*

* **Import Duration:** Histogramm der Zeit pro Import-Datei (ASCII-Batch).
* **Records per Second:** Durchsatz der verarbeiteten Reiter/Pferde/Vereine während eines Imports.
* **Idempotency Skip Rate:** Anteil der übersprungenen Datensätze (bereits vorhanden/unverändert).
* **Validation Error Rate:** Anteil der Datensätze, die aufgrund von Validierungsfehlern abgelehnt wurden.

### 1.2 API Performance Dashboard

*Fokus: Ktor REST-Endpunkte (Lese-Kanal).*

* **Request Latency (P95/P99):** Latenz der GET-Endpunkte (Target: < 150ms).
* **Request Rate (RPS):** Anzahl der Anfragen pro Sekunde.
* **HTTP Error Rate (4xx/5xx):** Verteilung der Fehlercodes.
* **Active Connections:** Anzahl der parallelen Ktor/Netty Verbindungen.

### 1.3 Database Health Dashboard

*Fokus: Exposed/Postgres Persistenz.*

* **Connection Pool Usage:** Aktive vs. maximale Verbindungen.
* **Query Latency:** Dauer der SQL-Statements (Top 10 langsamste Queries).
* **Table Size Growth:** Wachstum der Core-Tabellen (`reiter`, `horse`).
* **Migration Status:** Flyway-Migrationsstatus und Schema-Version.

### 1.4 System Resources Dashboard

*Fokus: JVM & Infrastruktur.*

* **JVM Heap Usage:** Speicherverbrauch des Spring/Ktor Hybrid-Prozesses.
* **CPU Load:** CPU-Auslastung des Containers.
* **GC Pauses:** Dauer und Frequenz der Garbage Collection.
* **File Descriptors:** Auslastung der Datei-Handles (kritisch für Netty).

---

## 2. Alarm-Regeln (Alerts)

| ID    | Alarm Name              | Bedingung                                              | Priorität |
|-------|-------------------------|--------------------------------------------------------|-----------|
| AL-01 | **API High Error Rate** | > 1% 5xx Fehler über 5 Minuten                         | Kritisch  |
| AL-02 | **Slow API Requests**   | P95 Latenz > 500ms für 2 Minuten                       | Warnung   |
| AL-03 | **Import Failure**      | Fehlerrate > 5% bei einem Batch-Lauf                   | Kritisch  |
| AL-04 | **DB Pool Exhausted**   | Pool-Auslastung > 90% für 1 Minute                     | Kritisch  |
| AL-05 | **JVM OOM Risk**        | Heap Usage > 85% nach Full GC                          | Kritisch  |
| AL-06 | **Rule-Set Mismatch**   | Mehrere aktive `RegulationConfig` Versionen pro Sparte | Warnung   |

---

## 3. Implementierungs-Details

* **Metriken-Export:** Prometheus-Format via `/actuator/prometheus` (Port 8081).
* **Tracing:** Optional via Micrometer Tracing (Brave/Zipkin), falls global im Projekt aktiviert.
* **Logging:** Strukturiertes Logging via Logback (ISO8601, TraceContext).