publish_timing_analysis/3_experiment_design/README.md

# 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.