load_appendix_analysis/alert_definition_specification/README.md

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