Stefan Mogeritsch 2f17778df6 feat(masterdata): introduce Regulation domain with API, persistence, and metrics integration

- Added `RegulationRepository` and its `Exposed` implementation for persistence.
- Implemented REST endpoints for regulations (`/rules`) in `RegulationController`, including support for tournament classes, license matrix, guidelines, fees, and configuration retrieval.
- Integrated OpenAPI documentation for `/rules` endpoints with Swagger UI in `masterdataApiModule`.
- Enabled Micrometer-based metrics for Prometheus in the API layer.
- Updated Gradle dependencies to include OpenAPI, Swagger, and Micrometer libraries.
- Registered `RegulationRepository` and `RegulationController` in `MasterdataConfiguration`.
- Improved database access patterns and reduced repetitive validation logic across domain services.
- Added unit and application tests for `RegulationController` to verify API behavior and repository interactions.
- Updated the service's `ROADMAP.md` to mark API v1 endpoints and observability as complete.

Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>

2026-03-30 15:38:18 +02:00

2.8 KiB

Raw Blame History

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

2.8 KiB Raw Blame History