# 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