From 6de88d7691f7eb431aa03222089a10abeb435ad2 Mon Sep 17 00:00:00 2001
From: Mika <kontakt@donau2space.de>
Date: Thu, 12 Mar 2026 11:51:47 +0000
Subject: [PATCH] Add alert_definition_specification/README.md

---
 alert_definition_specification/README.md | 172 +++++++++++++++++++++++
 1 file changed, 172 insertions(+)
 create mode 100644 alert_definition_specification/README.md

diff --git a/alert_definition_specification/README.md b/alert_definition_specification/README.md
new file mode 100644
index 0000000..78b20c9
--- /dev/null
+++ b/alert_definition_specification/README.md
@@ -0,0 +1,172 @@
+# Spezifikation des 'Max-only' Alert-Mechanismus
+
+## Purpose
+
+Definiert die technische Auslöse-, Deduplizierungs- und Routinglogik für den Max-only Alert auf Basis von Latenz-Outliern in Lasttests.
+
+**Problemstellung:** Unter Last entstehen beobachtbare, aber seltene Outlier-Ereignisse im near-expiry-unpinned-Stratum. Diese sollen transparent geloggt, aber nicht systemweit als Fehler gewertet werden.
+
+**Ziele:**
+- Identifikation signifikanter Latenzspitzen (Outlier)
+- Begrenzung unnötiger Logeinträge durch deduplizierte Ereigniserfassung
+- Schaffung eines eigenen Log-Kanals für reproduzierbare Extremfälle ohne Alert-Spam
+
+## Kontext & Hintergrund
+
+Runs #18 bis #20, jeweils 2× und 4× Parallelität, mit Latenzmetriken und Retry-Daten.
+
+**Gruppierung:**
+- Stratum (near-expiry-unpinned, pinned, etc.)
+- Parallelität (2×, 4×)
+
+**Trace-Metadaten / zusätzliche Tags:**
+- corr_id
+- key
+- runner_class
+- expires_at_dist_hours
+
+**Domänenkontext:**
+- Performanceanalyse unter variabler Parallelität
+- Systematische Erfassung von Latenzspitzen
+- Kontextualisierung von Near-Expiry-Outliern
+
+**Outlier-Definition:**
+- Methode: Schwellenbasierte Identifikation
+- Beschreibung: Ein Request wird als Outlier gewertet, wenn latency_ms > 90ms oder latency_ms > run_p99_ms.
+- Metrik: latency_ms
+
+**Motivation:**
+- Trennung von zufälligen Latenzspitzen und systematischen Mustern
+- Vermeidung unnötiger Alarmierung bei kontrollierbaren Extremwerten
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Für jeden Request wird die Latenz geprüft und mit definierten Schwellwerten verglichen.
+- Bei Überschreitung erfolgt ein Logeintrag im max_only-Channel.
+- Dedupe-Logik verhindert Mehrfacheinträge pro Key im 10-Minuten-Fenster.
+
+**Algorithmen / Verfahren:**
+- 1. Berechne run_p99_ms für aktuellen Run.
+- 2. Prüfe latency_ms >= 90ms oder >= run_p99_ms + delta_ms (optional).
+- 3. Wenn true, bilde outlier_bucket 'gt_90ms'.
+- 4. Sammle Payload-Felder und schreibe in max_only-Log-Channel mit MODE=warn.
+- 5. Wende Dedupe-Regel (pro run_id/key, Zeitfenster 10 Minuten) an.
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+**Software:**
+- Tracing-, Logging- und Performance-Monitoring-Integration aktiv
+
+**Konfiguration:**
+- Definierte Schwellwerte für Outlier und run_p99_ms
+- Aktivierter max_only Log-Channel
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- corr_id
+- key
+- stratum
+- job_parallelism
+- runner_class
+- expires_at_dist_hours
+- t_gate_read
+- t_index_visible
+- retry_taken
+- retry_total_overhead_ms
+- outlier_bucket
+
+**Formatbeispiele:**
+- { 'corr_id': 'abcd1234', 'latency_ms': 112, 'outlier_bucket': 'gt_90ms' }
+
+**Trace-Daten:**
+- Format: Structured JSON log entries
+- Hinweis: Einträge werden nur bei Outlier-Fällen generiert.
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- Anteil >90ms pro Stratum
+- Anteil >p99 pro Run
+
+**Vergleichsausgaben:**
+- 2× Parallelität vs 4× Parallelität
+  - Δ: Signifikant höherer Outlier-Anteil bei 4×
+
+- C-State-Korrelation: Nicht signifikant, Fokus auf near-expiry-unpinned-Stratum
+- Trace-Muster: Clusterbildung in gleichen Jobklassen bei 4× Runs
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Latenzmetriken pro Run extrahieren
+- Outlier-Kriterium anwenden
+- Max-only-Payload generieren
+- Dedupe-Regel ausführen
+- Ergebnisse in max_only-Channel schreiben
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Ermöglicht gezielte Analyse von Max-Outliern über mehrere Runs
+
+**Erforderliche Tags & Metadaten:**
+- latency_ms
+- run_p99_ms
+- stratum
+- job_parallelism
+- corr_id
+
+**trace-cmd-Setup:**
+- Ensure metric collection with ms granularity
+- Synchronisiere Run-Metadaten zentral
+
+**Run-Design für Contributors:**
+- Nutze konsistente Parallelitätsstufen (2×, 4×)
+- Erfasse retry_overhead getrennt pro Stratum
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Outlier treten reproduzierbar im near-expiry-unpinned-Stratum auf.
+- Retry-Overhead bleibt stabil bis leicht erhöht unter 4×, ohne globale Drift.
+- Der Max ist operativ relevant, aber kein Fehlerindikator.
+
+**Implikationen für Experimente:**
+- Ziel ist Beobachtbarkeit, nicht Schwellenverschärfung.
+- Weitere Runs dienen Validierung des Max-only-Routings.
+
+**Planungsziel:**
+- Ziel: Stabile Alerting-Basis für reproduzierbare Extremfälle schaffen.
+- Vorgehen:
+  - Outlier als Diagnoseobjekte behandeln
+  - Keine Policy-Änderung vor vollständiger Validierung
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Schwankungen der p99-Schwelle zwischen Runs erschweren direkte Vergleichbarkeit.
+
+**Kausalität & Generalisierbarkeit:**
+- Ergebnisse gelten für beobachtete Lastfenster, nicht notwendigerweise für andere Systemkonfigurationen.
+
+**Praktische Fallstricke:**
+- Zu niedrige Dedupe-Fenster könnten Ereignisse mehrfach loggen.
+- Fehlende Synchronisierung von run_p99_ms führt zu inkonsistenter Auslösung.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- 4× Run mit aktiviertem Max-only-Routing zur Validierung der Logik
+
+**Analyseziele:**
+- Vergleich zwischen Pre- und Post-Routing Performance-Verteilung
+
+**Regression & Modellierung:**
+- Evaluieren, ob Outlier-Verhalten durch Caching- oder Scheduling-Variablen modellierbar ist
+
+**Community-Beiträge:**
+- Bereitstellung des Alert-Templates für andere Analysegruppen