Add frozen_runs_report/README.md

frozen_runs_report/README.md

@@ -0,0 +1,230 @@
+# Frozen-Runs Analyse – Zwischenbericht zu Metriken und Timing-Effekten
+
+## Purpose
+
+Analyse von Frozen-Runs zur Untersuchung von Timing-Stabilität und Metrikunterschieden zwischen pinned und unpinned CPU-Konfigurationen.
+
+**Problemstellung:** Unklarheit über die Stabilität und Wiederholbarkeit von Timing-Metriken bei Frozen-Runs unter verschiedenen CPU-Bindungszuständen (pinned vs. unpinned).
+
+**Ziele:**
+- Vergleich der Metriken Mischfenster-Dauer, Retry-free-in-window Rate und seqcount_retry_count zwischen pinned und unpinned Runs
+- Bewertung der metrischen Robustheit mittels Bootstrap-Konfidenzintervallen
+- Identifikation belastbarer Trennmerkmale als Grundlage für spätere CI-Gates
+
+## Kontext & Hintergrund
+
+Vier N40-Frozen-Runs (#20–#23) mit balanciertem Setup: pinned/unpinned alternierend, keine back-to-back-Ausführungen.
+
+**Gruppierung:**
+- pinned_flag
+
+**Trace-Metadaten / zusätzliche Tags:**
+- corr_id
+- write_pre
+- write_post
+- clocksource_switch
+
+**Domänenkontext:**
+- System Performance Analysis
+- CPU Binding Effects
+- Timing Stability in Benchmark Runs
+
+**Outlier-Definition:**
+- Methode: Empirisch über Bootstrap-Stabilität der p95/max-Metriken
+- Beschreibung: Ausreißer sind Runs, deren Metrikbeiträge stark variieren und über die Bootstraps nicht stabil reproduzierbar sind.
+- Metrik: Mischfenster-Dauer (p95, max)
+
+**Motivation:**
+- Validierung der Frozen-Runs als stabile Baseline
+- Quantifizierung der Einflüsse von CPU-Pinning auf Timing-Streuung
+- Vorbereitung auf CI-taugliche Gate-Metriken
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Balanciertes Frozen-Run-Design mit 2x pinned und 2x unpinned Ausführungen.
+- Sanity-Checks zur Sicherstellung der Datenintegrität vor Analyse.
+- Bootstrap-Resampling über Runs zur Robustheitsbewertung der Effektgrößen.
+
+**Algorithmen / Verfahren:**
+- Berechnung von p50, p95 und max der Mischfenster-Dauer pro Run.
+- Berechnung der retry-free-in-window Rate und Korrelation mit seqcount_retry_count.
+- Bootstrap-Resampling (n=10.000) über Runs, gruppiert nach pinned_flag.
+- Berechnung von Effektgrößen (rank-biserial Correlation, Cliff’s delta).
+
+### Bootstrap-Übersicht
+
+Resampling-Verfahren zur Schätzung von Konfidenzintervallen und Stabilität von Effektgrößen.
+
+**Zielgrößen:**
+- p95 Mischfenster-Dauer
+- retry-free-in-window Rate
+- Cliff’s delta pro Metrik
+
+### Resampling-Setup
+
+- pinned
+- unpinned
+
+**Stichprobeneinheit:** Run
+
+**Resampling-Schema:**
+- 10.000 Resamples pro Gruppe mit Replacement
+
+**Konfidenzintervalle:**
+- Niveau: 0.95
+- Typ: percentile
+- Ableitung: aus den empirischen Bootstrap-Verteilungen
+
+### Abgeleitete Effektgrößen
+
+**Risk Difference (Differenz der Raten):**
+- Definition: Differenz der retry-free-in-window Raten zwischen pinned und unpinned Runs.
+- Bootstrap: Bootstrapped 95%-Konfidenzintervall über Gruppenmittelwerte.
+
+**Risk Ratio:**
+- Definition: Relatives Risiko eines niedrigen retry-free Anteils bei unpinned Runs.
+- Bootstrap: Bootstrap-Schätzung der RR-Verteilung über Run-Resamples.
+
+### C-State-Kontrolle
+
+**Ziel:** Vermeidung von Störfaktoren durch CPU-Zustandswechsel (C-States).
+
+**Vorgehen:**
+- Frozen-Setup ohne Dynamikänderungen von CPUFreq governor.
+- Enge Kontrolle über run sequence und clocksource stability.
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- Mehrkernsystem mit identischen Cores
+- CPU-Pinning-Unterstützung im Kernel
+
+**Software:**
+- trace-cmd
+- Auswerteskripte mit Bootstrap-Unterstützung
+- Statistik-Tool für Effektgrößen
+
+**Konfiguration:**
+- Frozen-Setup aktiv
+- Clocksource switch tracebar
+- Keine parallelen Systemlasten
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- run_id
+- pinned_flag
+- mischfenster_p50
+- mischfenster_p95
+- mischfenster_max
+- retry_free_rate
+- seqcount_retry_count
+
+**Formatbeispiele:**
+- 21, unpinned, 1.2ms, 4.9ms, 7.3ms, 0.94, 12
+
+**Trace-Daten:**
+- Format: trace-cmd output mit clocksource_switch-Ereignissen
+- Hinweis: Jeder Trace enthält korrelierte write_pre/write_post-Einträge mit fortlaufenden corr_id-Werten.
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- p50
+- p95
+- max
+- bootstrap CI-Bereich
+- Cliff’s delta
+
+**Vergleichsausgaben:**
+- pinned vs unpinned
+  - Δ: retry-free-in-window Rate differiert um ca. mehrere Prozentpunkte
+  - CI(Δ): 95%-CI ohne Überlappung in einigen Runs
+  - RR: unpinned > pinned (breitere Tails, höhere Varianz)
+  - CI(RR): enge Bandbreite, robuste Trennung beim p95
+
+- C-State-Korrelation: nicht signifikant unter frozen setup
+- Trace-Muster: unpinned zeigt breitere Latenzverteilungen im Mischfenster
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Alle Runs erfassen und sanity-check durchführen.
+- Kernmetriken extrahieren und pro Run speichern.
+- Bootstrap-Resampling mit Gruppierung nach pinned_flag ausführen.
+- Effektgrößen und Konfidenzintervalle vergleichen und validieren.
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Eindeutige Erkennung der clocksource_switch- und write_pre/post-Ereignisse.
+
+**Erforderliche Tags & Metadaten:**
+- corr_id
+- run_id
+- pinned_flag
+- timestamp
+
+**trace-cmd-Setup:**
+- trace-cmd record -e clocksource:*
+- constantes Tracing-Intervall pro Run
+
+**Run-Design für Contributors:**
+- abwechslungsweise pinned/unpinned Läufe
+- keine Back-to-back-Ausführung
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- unpinned Runs zeigen erhöhte Varianz in p95 und max Mischfenster-Dauer.
+- retry-free-in-window Rate bleibt über Gruppen stabil mit engen CIs.
+- Bootstrap-Schätzungen trennen signifikant auch bei kleinen Run-Zahlen.
+
+**Implikationen für Experimente:**
+- p95 ist robustere Metrik als max für künftige CI-Gates.
+- retry-free-in-window eignet sich als ergänzender Stabilitätsindikator.
+
+**Planungsziel:**
+- Ziel: Vorbereitung auf CI-basierte Metrik-Gates für Performance-Regression-Checks.
+- Vorgehen:
+  - Kombination von Effektgröße und Bootstrap-CI als Entscheidungskriterium
+  - Identifikation von stabilen Metriken mit geringer CI-Streuung
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Kleine Stichprobenzahl (n=4) limitiert Teststärke.
+- Frozen-Setup kann externe Effekte kaschieren.
+- Keine volle Zeitreproduzierbarkeit bei möglichen Migrationen außerhalb frozen runs.
+
+**Bootstrap-spezifische Limitationen:**
+- Bootstrap stabilisiert nur im Rahmen vorhandener Varianz.
+- Run-Korrelationen können zu unterschätzten CIs führen.
+
+**Kausalität & Generalisierbarkeit:**
+- Effekte gelten nur für identisches Hardware-Setup.
+- Keine kausale Aussage über CPU-Pinning allgemein.
+
+**Praktische Fallstricke:**
+- clocksource_switch Events müssen vollständig geloggt sein.
+- Fehlende corr_id oder write_post können Analyse verzerren.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Zusätzliche 4–6 Runs im strict frozen Setup.
+- Gate-Prototyp zur Bewertung stabiler Metriken.
+
+**Analyseziele:**
+- CI-fähiger Vergleich von p95 vs. retry-free-in-window als Leitmetrik.
+- Überprüfung der Bootstrap-Verlässlichkeit bei größeren Samples.
+
+**Regression & Modellierung:**
+- Einführung einfacher Gate-Prototypen ohne harte Schwellen.
+- Langfristig Modellierung von Timing-Varianz über pinned vs. unpinned.
+
+**Community-Beiträge:**
+- Feedback zu priorisierten Gate-Metriken einholen (p95 vs retry-free).
+- Offene Diskussion über standardisierte Frozen-Benchmarks.