Add cstate_logging_template/README.md

cstate_logging_template/README.md

@@ -0,0 +1,226 @@
+# Template für C-State-Logging mit trace-cmd und BPF-Tracing
+
+## Purpose
+
+Beschreibung eines Templates zur konsistenten Erfassung von CPU-C-State-Residencies und Governor-Metadaten im Rahmen von Mikrobenchmark-Analysen.
+
+**Problemstellung:** Unterschiedliche CPU-Governor- und C-State-Konfigurationen beeinflussen Messungen von Latenz und Stabilität; eine standardisierte Logging-Vorlage ermöglicht Vergleichbarkeit und Integration von Trace-Daten in Bootstrap-basierte Auswertungen.
+
+**Ziele:**
+- Sicherstellen reproduzierbarer C-State-Log-Erhebung unter Linux
+- Unterstützung der Bootstrap-Analyse von Outlier-Raten in Abhängigkeit des Governors
+- Bereitstellung einer strukturierten Vorlage für Community-Beiträge
+
+## Kontext & Hintergrund
+
+Benchmark-Läufe (~240 Runs), gruppiert nach CPU-Governor mit Outlier-Markierung und C-State-Metadaten.
+
+**Gruppierung:**
+- powersave
+- performance
+
+**Trace-Metadaten / zusätzliche Tags:**
+- C-State-Residency-Tags
+- Governor-Name
+- Zeitstempel
+
+**Domänenkontext:**
+- Linux CPU power management
+- Governor tuning
+- Outlier detection in performance benchmarks
+
+**Outlier-Definition:**
+- Methode: Median/IQR-basiert
+- Beschreibung: Ein Run gilt als Outlier, wenn sein Messwert außerhalb des 1.5*IQR-Fensters um den Median der Gruppe liegt.
+- Metrik: Benchmark Response Time / Execution Time
+
+**Motivation:**
+- Quantifizierung der Stabilitätsunterschiede zwischen Governors
+- Integration von C-State-Informationen zur Reduktion systematischer Fehlklassifikationen
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Bootstrap-basierte Resampling-Analyse der Outlier-Anteile pro Governor.
+- Verwendung von trace-cmd und BPF-Tracing zur Erfassung von C-State-Residency-Metadaten.
+- Kontrolle eingehender Logs auf korrekte Governor-Zuordnung.
+
+**Algorithmen / Verfahren:**
+- 10.000 Bootstrap-Resamples der Outlier-Anteile pro Governor-Gruppe.
+- Berechnung der 95%-Konfidenzintervalle der geschätzten Outlier-Rate.
+- Bestimmung der Differenz der Outlier-Anteile und der Risk-Ratio mit eigenen Bootstrap-Intervallen.
+
+### Bootstrap-Übersicht
+
+Nichtparametrische Resampling-Methode zur Schätzung von Verteilungen und Konfidenzintervallen aus empirischen Daten.
+
+**Zielgrößen:**
+- Outlier-Anteil pro Governor
+- Differenz der Anteile
+- Risk Ratio
+
+### Resampling-Setup
+
+- powersave
+- performance
+
+**Stichprobeneinheit:** Benchmark-Run
+
+**Resampling-Schema:**
+- Zufälliges Ziehen von N Stichproben pro Gruppe mit Zurücklegen, N = Gruppengröße
+
+**Konfidenzintervalle:**
+- Niveau: 0.95
+- Typ: percentile
+- Ableitung: aus 10.000 Bootstrap-Samples
+
+### Abgeleitete Effektgrößen
+
+**Risk Difference (Differenz der Raten):**
+- Definition: Differenz der Outlier-Anteile zwischen powersave und performance.
+- Bootstrap: Verteilung der Differenzen aus gepaarten Bootstrap-Samples.
+
+**Risk Ratio:**
+- Definition: Quotient der Outlier-Anteile (powersave/performance).
+- Bootstrap: Log-transformierte Bootstrap-Verteilung zur Stabilisierung der Schätzvarianz.
+
+### C-State-Kontrolle
+
+**Ziel:** Sicherstellung, dass Runs identische C-State-Muster je Governor aufweisen.
+
+**Vorgehen:**
+- Erfassung der CPU-C-State-Residencies per BPF oder trace-cmd plugin powermgmt
+- Tagging in Trace-Metadaten
+- Filterung fehlerhafter oder unzureichend annotierter Runs
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- Linux-System mit CPU-Governor-Support
+- Trace-fähiger Kernel (ftrace, BPF, trace-cmd)
+
+**Software:**
+- trace-cmd ≥ v2.9
+- BPF-Tooling (bcc oder bpftrace)
+- Python für Bootstrap-Auswertung
+
+**Konfiguration:**
+- Aktiver Governor über cpufreq-set
+- C-State-Logging mit trace-cmd record --event power:* oder angepassten BPF-Probes
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- timestamp
+- governor
+- metric_value
+- outlier_flag
+- cstate_residencies
+
+**Formatbeispiele:**
+- 2024-02-12T10:15:33Z, performance, 5.62, 0, {C1=23%,C2=77%}
+
+**Trace-Daten:**
+- Format: FTRACE/trace-cmd binary (.dat) mit BPF-Erweiterungen
+- Hinweis: Muss C-State-Events und Governor-Tag enthalten.
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- Outlier-Rate
+- 95%-Konfidenzintervall
+- Mean/Median Execution Time
+
+**Vergleichsausgaben:**
+- powersave vs performance
+  - Δ: ≈19.0 [10.1, 28.7]
+  - CI(Δ): [10.1, 28.7]
+  - RR: ≈4.3
+  - CI(RR): [2.0, 9.6]
+  - Tests: Mann-Whitney p≈0.006
+
+- C-State-Korrelation: Analyse des Zusammenhangs zwischen C-State-Tiefe und Outlier-Wahrscheinlichkeit
+- Trace-Muster: Erkennung wiederkehrender Idle-State-Übergänge in powersave-Modi
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- trace-cmd record starten mit Governor-Tag und C-State-Erfassung
+- Benchmark-Run durchführen
+- trace-cmd report erstellen
+- Parsing der Metadaten in tabellarisches Format
+- Bootstrap-Resampling pro Gruppe ausführen
+- Statistische Kennzahlen und Intervalle berechnen
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Standardisierte Erhebung für vergleichbare Analysen zwischen Systemen
+
+**Erforderliche Tags & Metadaten:**
+- governor
+- timestamp
+- benchmark_id
+- cstate_residencies
+
+**trace-cmd-Setup:**
+- trace-cmd record -e power --buffer-size=32768 --date --output=run.dat
+- Erweiterung durch BPF-Probe für cpu_idle_enter/exit zur C-State-Auflösung
+
+**Run-Design für Contributors:**
+- Paare aus jeweils einem powersave- und einem performance-Run unter identischen Bedingungen
+- Mindestens 50 gepaarte Runs zur Bootstrap-Auswertung
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- powersave zeigt etwa vierfach erhöhte Outlier-Wahrscheinlichkeit gegenüber performance
+- Bootstrap-Konfidenzintervalle überschneiden sich nicht zwischen Gruppen
+- Konsistenz zwischen Bootstrap- und Mann-Whitney-Ergebnissen
+
+**Implikationen für Experimente:**
+- C-State und Governor müssen in weiteren Performance-Analysen als feste Kovariaten behandelt werden
+- Geplante Replikation mit 24h-Holdover-Setup zur Stabilitätsprüfung
+
+**Planungsziel:**
+- Ziel: Präzisierung der Schätzgenauigkeit in späteren Runs
+- Vorgehen:
+  - Stichprobenumfang planen, sodass CI-Breite ±3 Prozentpunkte beträgt
+  - Fixierte Governor-Konfigurationen im Dauerbetrieb testen
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Begrenzte Run-Anzahl kann Bootstrap-Schätzfehler erhöhen
+- Ungenügende C-State-Annotation führt zu Fehlklassifikation
+
+**Bootstrap-spezifische Limitationen:**
+- Nichtparametrische Resampling-Fehler bei stark ungleichen Gruppen
+- Abhängigkeit von der Varianzstruktur der Originaldaten
+
+**Kausalität & Generalisierbarkeit:**
+- Korrelation, keine kausale Beweisführung für Governor-Effekte
+- Hardware-spezifische C-State-Implementierung limitiert Generalisierbarkeit
+
+**Praktische Fallstricke:**
+- Fehlende Synchronisation von Loggerzeitstempeln bei Multi-Core-Benchmarks
+- Unzureichende Buffer-Größe führt zu verlorenen Trace-Ereignissen
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- 24h Holdover-Test für beide Governor-Konfigurationen mit vollständigem C-State-Logging
+- BPF-basierte Echtzeit-Analyse von C-State-Residency während Lastumschaltungen
+
+**Analyseziele:**
+- Replikation der Bootstrap-Effekte unter stabileren Bedingungen
+- Ableitung von Varianzmodellen für Governor-Wechsel
+
+**Regression & Modellierung:**
+- Logistische Regression der Outlier-Wahrscheinlichkeit vs. C-State-Residency
+- Nichtlineare Modelle zur Quantifizierung des Stromspar-Verzögerungseinflusses
+
+**Community-Beiträge:**
+- Bereitstellung eines Repo-Templates für Mitwirkende
+- Sammeln anonymer governor-getaggter Traces zur Meta-Analyse