Add 3_experiment_design/README.md

3_experiment_design/README.md

@@ -0,0 +1,235 @@
+# A/B-Experiment-Design: Pinned vs. Unpinned Publish-Bedingungen
+
+## Purpose
+
+Definition und Dokumentation des A/B-Experiment-Designs zur Bewertung von Publish-Timelines bei pinned und unpinned Bedingungen.
+
+**Problemstellung:** Die Position des ersten retry-freien Reads in der Publish-Sequenz ist nicht stabil. Es muss untersucht werden, ob CPU-Pinning das Mischfenster zwischen relevanten Write-Events verkleinert.
+
+**Ziele:**
+- Analyse des Einflusses von CPU-Pinning auf Publish-Timing-Zonen.
+- Bestimmung der relativen Häufigkeit von Reads zwischen spezifischen Write-Schritten.
+- Quantifizierung typischer Mischfenster-Dauern (p50, p95, max).
+
+## Kontext & Hintergrund
+
+Trace-Daten pro corr_id mit Write-Events und zugehörigen Read-Events.
+
+**Gruppierung:**
+- Case_03
+- Case_04
+- pinned
+- unpinned
+
+**Trace-Metadaten / zusätzliche Tags:**
+- base_raw_write
+- nsec_base_write
+- baseline_recalc_enter
+- baseline_recalc_exit
+- clocksource_id_write
+
+**Domänenkontext:**
+- Low-Level-Timing-Analyse
+- eBPF-Instrumentation
+- System-Performance-Validierung
+
+**Outlier-Definition:**
+- Methode: absolute duration cutoff
+- Beschreibung: Events mit extrem hohen Latenzen werden ausgeschlossen, wenn sie oberhalb 3×p95 liegen.
+- Metrik: Zeitdifferenz zwischen aufeinanderfolgenden Writes oder Reads
+
+**Motivation:**
+- Ermittlung von Übergangsphasen im Publish-Prozess.
+- Validierung von baseline_recalc als relevanter Segmentierungspunkt.
+- Untersuchung des Einflusses von CPU-Pinning auf Publish-Timing-Kohärenz.
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Pro corr_id werden Write- und Read-Events kombiniert.
+- Reads werden einer Zone zwischen definierten Write-Schritten zugeordnet.
+- Vergleich von Zonenverteilungen zwischen pinned und unpinned Gruppen.
+
+**Algorithmen / Verfahren:**
+- Instrumentiere Write-Events mit field_tags (base_raw_write, nsec_base_write).
+- Instrumentiere baseline_recalc_enter/exit als Marker.
+- Aggregiere Events per corr_id in trace_agg.py zu Step-Listen.
+- Klassifiziere Reads nach Position zwischen Steps (read_between_steps).
+- Berechne Häufigkeiten und Dauerstatistiken pro Zone (p50, p95, max).
+
+### Bootstrap-Übersicht
+
+Bootstrap-Resampling zur Stabilisierung von Zonenantailschätzungen.
+
+**Zielgrößen:**
+- Anteil Reads vor baseline_recalc_exit
+- Anteil Reads vor clocksource_id_write
+
+### Resampling-Setup
+
+- Case_03-pinned
+- Case_03-unpinned
+- Case_04-pinned
+- Case_04-unpinned
+
+**Stichprobeneinheit:** corr_id
+
+**Resampling-Schema:**
+- Bootstrap n=10k Wiederholungen pro Gruppe
+
+**Konfidenzintervalle:**
+- Niveau: 0.95
+- Typ: Percentile-Interval
+- Ableitung: Resampling-Anteile
+
+### Abgeleitete Effektgrößen
+
+**Risk Difference (Differenz der Raten):**
+- Definition: Differenz des Anteils von Reads in Zone 1 zwischen pinned und unpinned Gruppen.
+- Bootstrap: Bootstrap-Schätzung mit 95%-Konfidenzintervall
+
+**Risk Ratio:**
+- Definition: Quotient der Wahrscheinlichkeiten für Reads in Zone 1 (pinned/unpinned).
+- Bootstrap: Bootstrap-Resampling von Verhältniswerten
+
+### C-State-Kontrolle
+
+**Ziel:** Vermeidung verfälschter Timings durch unterschiedliche C-State-Zustände.
+
+**Vorgehen:**
+- Logge CPU-Frequenz und aktuelle C-State-Transitions während der Runs.
+- Filtere Runs mit Frequenzabweichungen > ±5% des Sollwerts.
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- x86_64-System mit konfigurierbarem CPU-Pinning
+
+**Software:**
+- Linux Kernel mit eBPF-Unterstützung
+- trace-cmd
+- Python 3.10+ mit NumPy/Pandas
+
+**Konfiguration:**
+- Zuweisung pinned/unpinned Threads zu festen CPUs
+- Aktivierte ftrace tracepoints für publish_write-Events
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- corr_id
+- event_name
+- ktime_ns
+- cpu
+- new_value_hash
+
+**Formatbeispiele:**
+- 1234,base_raw_write,1749827412,2,0x89ad23
+
+**Trace-Daten:**
+- Format: ftrace / trace-cmd binary
+- Hinweis: Parsed über trace_agg.py in standardisierte JSON-Struktur
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- p50
+- p95
+- max Dauer pro Zone
+
+**Vergleichsausgaben:**
+- Case_03-pinned vs Case_03-unpinned
+  - Δ: ΔZone1_Anteil
+  - CI(Δ): 95%-CI[low,high]
+  - RR: ratio_Zone1_pinned/unpinned
+  - CI(RR): 95%-CI_ratio
+- Case_04-pinned vs Case_04-unpinned
+  - Δ: ΔZone1_Anteil
+  - CI(Δ): 95%-CI[low,high]
+  - RR: ratio_Zone1_pinned/unpinned
+  - CI(RR): 95%-CI_ratio
+
+- C-State-Korrelation: Analyse der Relation zwischen Zone-Dauer und CPU-State
+- Trace-Muster: Liste typischer Eventreihenfolgen pro corr_id
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Run-Setup für pinned und unpinned Gruppen mit identischem Workload.
+- Trace-Aufzeichnung und Speicherung der Write-/Read-Events.
+- Parsing über trace_agg.py zu Step-Sequenzen pro corr_id.
+- Zonenzuordnung und Aggregation der Statistiken.
+- Bootstrap-Auswertung zur Unsicherheitsabschätzung.
+- Vergleich der pinned/unpinned Resultate und Berechnung von Effektmaßen.
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Reproduzierbare Messung von Publish-Schritt-Sequenzen pro corr_id.
+
+**Erforderliche Tags & Metadaten:**
+- base_raw_write
+- nsec_base_write
+- baseline_recalc_enter
+- baseline_recalc_exit
+- clocksource_id_write
+
+**trace-cmd-Setup:**
+- trace-cmd record -e base_raw_write -e nsec_base_write -e baseline_recalc_* -e clocksource_id_write
+
+**Run-Design für Contributors:**
+- N=10–20 Runs pro Case, gemischte corr_ids, stabile Workloadbedingungen
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Reads treten meist zwischen base_raw_write/nsec_base_write und baseline_recalc_exit auf.
+- baseline_recalc segmentiert den Publish-Zyklus in zwei signifikante Zonen.
+- CPU-Pinning kann die Zone-1-Länge und relative Read-Anteile verringern.
+
+**Implikationen für Experimente:**
+- Pinning könnte deterministischere Publish-Timelines erzeugen.
+- Verzögerungen in baseline_recalc wirken sich messbar auf Read-Positionen aus.
+
+**Planungsziel:**
+- Ziel: Quantitative Beurteilung des Einflusses von CPU-Pinning auf Publish-Synchronität.
+- Vorgehen:
+  - A/B-Vergleich pinned/unpinned
+  - Bootstrapping für robuste Schätzwerte
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Kleine Stichprobe (N<20) limitiert Aussagekraft.
+- Fehlerhafte corr_id-Zuordnung kann Reads in falsche Zone klassifizieren.
+
+**Bootstrap-spezifische Limitationen:**
+- Bootstrap-Schätzung kann bei ungleichen Gruppengrößen verzerrt sein.
+- Resampling ohne Berücksichtigung korrelierter Runs kann Overconfidence erzeugen.
+
+**Kausalität & Generalisierbarkeit:**
+- Ergebnisse gelten nur für die getestete Architektur.
+- Kausale Interpretation nur eingeschränkt möglich ohne Task-Level-Trace.
+
+**Praktische Fallstricke:**
+- Unscharfe baseline_recalc-Marker führen zu fehlerhafter Zonenzuordnung.
+- Trace-Overhead durch zusätzliche Events kann selbst Timing beeinflussen.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Erweiterung auf größere N pro Case.
+- Variation der CPU-Affinität innerhalb der pinned Gruppe.
+
+**Analyseziele:**
+- Bewertung zusätzlicher Zwischenzonen (post-clocksource_id_write).
+- Zeitliche Analyse vor baseline_recalc_enter.
+
+**Regression & Modellierung:**
+- Lineares Modell der Mischfenster-Dauer als Funktion von CPU-Last und Pinning.
+- Bootstrap-basierte Modellvalidierung.
+
+**Community-Beiträge:**
+- Austausch über Instrumentation von baseline_recalc.
+- Vergleichbarkeit der Marker über verschiedene Kernel-Versionen.