From b51c89ccaa543f2800964523280935908ab8ff31 Mon Sep 17 00:00:00 2001
From: Mika <kontakt@donau2space.de>
Date: Sat, 6 Dec 2025 13:41:17 +0000
Subject: [PATCH] Add trace_repo_template/README.md

---
 trace_repo_template/README.md | 230 ++++++++++++++++++++++++++++++++++
 1 file changed, 230 insertions(+)
 create mode 100644 trace_repo_template/README.md

diff --git a/trace_repo_template/README.md b/trace_repo_template/README.md
new file mode 100644
index 0000000..a27673a
--- /dev/null
+++ b/trace_repo_template/README.md
@@ -0,0 +1,230 @@
+# Trace-Repo-Template und Aggregationsskript für C-State- und Clocksource-Analysen
+
+## Purpose
+
+Dokumentvorlage und Skriptstruktur zur Analyse von CPU-Governor-Einflüssen auf C-State-Residency und Clocksource-Wechsel über lange Testzeiträume.
+
+**Problemstellung:** Unterschiede im CPU-Governor-Verhalten über einen 24‑h‑Testzeitraum verursachen Outlier‑Cluster, deren Korrelation mit C‑State‑ und Clocksource‑Metriken reproduzierbar dokumentiert werden soll.
+
+**Ziele:**
+- Einheitliche Trace-Struktur für C-State-Analysen
+- Automatisierte Aggregation von Clocksource-Wechselereignissen
+- Vergleich von Governor-Profilen über gleichartige Runs
+
+## Kontext & Hintergrund
+
+Langzeit-Traces von CPU‑C‑States, Clocksource‑Wechseln und EM‑Messungen über 24‑h‑Runs unter verschiedenen CPU‑Governoren.
+
+**Gruppierung:**
+- powersave
+- performance
+
+**Trace-Metadaten / zusätzliche Tags:**
+- timestamp
+- cstate_level
+- clocksource_event
+- governor_mode
+- event_latency
+
+**Domänenkontext:**
+- CPU power management
+- kernel scheduler behavior
+- BPF tracing
+- bootstrap analysis
+
+**Outlier-Definition:**
+- Methode: Bootstrap-basiertes Resampling und Mann‑Whitney‑Test
+- Beschreibung: Outlier werden als Messungen außerhalb des 95 %-Konfidenzintervalls der Referenzgruppe definiert.
+- Metrik: Benchmark-Latenzabweichung pro Lauf
+
+**Motivation:**
+- Überprüfung des Governor‑Effekts über lange Zeiträume
+- Quantifizierung der C‑State‑Einflüsse auf Stabilität
+- Ausschluss elektrischer Störeinflüsse
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Vergleich der Outlier‑Raten zwischen powersave und performance Governors über 24 h
+- Analyse der C3‑Residency im 0–1000 ms‑Fenster vor Events
+- Auswertung von clocksource_switch‑BPF‑Traces
+
+**Algorithmen / Verfahren:**
+- Bootstrap‑Resampling mit 10 000 Iterationen, Ermittlung von 95 %‑Konfidenzintervallen
+- Differenz von Anteilen (Outlier‑Raten) zwischen Gruppen
+- Risikoquotient‑Schätzung (risk ratio)
+- Nonparametrische Signifikanztests mittels Mann‑Whitney‑U
+
+### Bootstrap-Übersicht
+
+Nichtparametrisches Resampling über Outlier‑Messungen pro Governor‑Gruppe.
+
+**Zielgrößen:**
+- Outlier‑Anteil
+- Median‑Residency C3
+- clocksource_switch‑Rate
+
+### Resampling-Setup
+
+- powersave
+- performance
+
+**Stichprobeneinheit:** Einzelner Benchmark‑Lauf
+
+**Resampling-Schema:**
+- 10 000 Iterationen
+- Mit Zurücklegen
+- Gruppenweise Resamples
+
+**Konfidenzintervalle:**
+- Niveau: 0.95
+- Typ: Percentilbasiert
+- Ableitung: Empirisch aus Bootstrap‑Verteilung
+
+### Abgeleitete Effektgrößen
+
+**Risk Difference (Differenz der Raten):**
+- Definition: Differenz der Outlier‑Raten zwischen Governors.
+- Bootstrap: Bootstrap‑Verteilung der Anteilsdifferenz, CI über Percentile.
+
+**Risk Ratio:**
+- Definition: Verhältnis der Outlier‑Wahrscheinlichkeiten zwischen powersave und performance.
+- Bootstrap: Resampling der Quotenverteilung und CI‑Schätzung über log‑Transformation.
+
+### C-State-Kontrolle
+
+**Ziel:** Validierung des Einflusses tiefer C‑States auf Outlier‑Rate.
+
+**Vorgehen:**
+- Zusätzlicher Kontrolllauf mit powersave, C0/C1‑only
+- Vergleich Outlier‑Rate gegenüber performance
+- Analyse C‑State‑Residency‑Reduktion
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- x86‑Laptop mit stabiler Stromversorgung
+- konstante Umgebungstemperatur
+
+**Software:**
+- Linux‑Kernel mit BPF‑Unterstützung
+- trace‑cmd
+- Python‑Bootstrap‑Auswerteskript
+
+**Konfiguration:**
+- Governor festgesetzt (powersave oder performance)
+- clocksource Kernel‑Trace aktiviert
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- timestamp
+- latency_ms
+- cstate
+- clocksource_event_count
+- governor
+- run_id
+
+**Formatbeispiele:**
+- 2024‑12‑01T06:00:00Z, 2.35 ms, C3, 1, powersave, run_01
+
+**Trace-Daten:**
+- Format: FTRACE/BPF‑Events im Text‑ oder JSON‑Exportformat
+- Hinweis: Jede Zeile enthält Event‑Timestamp und C‑State‑Wechselkennung.
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- Outlier‑Rate (%)
+- Median‑C3‑Residency (ms)
+- clocksource_switch‑Events pro Benchmark
+
+**Vergleichsausgaben:**
+- powersave vs performance
+  - Δ: ≈18 Prozentpunkte
+  - CI(Δ): [~12, 24]
+  - RR: ≈4.1
+  - CI(RR): [~2.0, 6.8]
+  - Tests: ≈0.003
+
+- C-State-Korrelation: Residency‑Zunahme in C3 korreliert mit Outlier‑Häufungen.
+- Trace-Muster: C‑State‑Exit gefolgt von clocksource_switch‑Event innerhalb 20–200 ms.
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Traces erfassen mit trace‑cmd oder BPF‑Programmen
+- Aggregationsskript aus Template anwenden
+- Bootstrap‑Analyse der Outlier‑Raten durchführen
+- Ergebnisse in Gruppen‑Report konsolidieren
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Standardisierte Aufnahme und Auswertung von C‑State‑Residency und Clocksource‑Wechseln.
+
+**Erforderliche Tags & Metadaten:**
+- governor
+- timestamp
+- cstate
+- clocksource_event
+- latency_ms
+
+**trace-cmd-Setup:**
+- trace‑cmd record ‑e power/cpu_idle ‑e clockevents/clock_*
+- BPF‑Tracing optional für clocksource_switch aktivieren
+
+**Run-Design für Contributors:**
+- Identische Hardware‑Parameter pro Lauf beibehalten
+- Getrennte Runs für powersave und performance
+- Laufzeit mindestens 24 h pro Konfiguration
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Governor‑Effekt bleibt über 24 h stabil nachweisbar.
+- powersave zeigt erhöhte Outlier‑Raten und tiefere C‑States.
+- C‑State‑Exits stehen in zeitlicher Nähe zu clocksource_switch‑Events.
+
+**Implikationen für Experimente:**
+- Governor‑Wahl beeinflusst zeitliche Stabilität von Benchmarks.
+- C‑State‑Management ist kritischer Faktor bei Latenzanalysen.
+
+**Planungsziel:**
+- Ziel: Reduktion der Outlier‑Rate durch gezielte C‑State‑Begrenzung.
+- Vorgehen:
+  - Kontrolllauf mit C0/C1‑Only‑Regime
+  - Analyse, ob Outlier‑Rate auf performance‑Niveau absinkt
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Langzeit‑Test unterliegt Temperatur‑ und Spannungsdrift.
+- Spätere Tageszyklen können Einfluss auf System‑Thermik haben.
+
+**Bootstrap-spezifische Limitationen:**
+- Abhängigkeit der CIs von der Stichprobengröße.
+- Bootstrap‑Verteilungen können bei kleinen N verzerrt sein.
+
+**Kausalität & Generalisierbarkeit:**
+- Beobachtete Korrelationen nicht zwingend kausal.
+- Ergebnisse spezifisch für getestete Hardware/Kernel‑Version.
+
+**Praktische Fallstricke:**
+- Falsche Governorumschaltung während Testlauf verfälscht Ergebnis.
+- Nicht‑synchronisierte Traces erschweren Zuordnung von Events.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Kontrolllauf mit powersave (nur C0/C1 erlaubt).
+
+**Analyseziele:**
+- Quantitative Validierung des Einflusses tiefer C‑States auf Outlier‑Raten.
+
+**Regression & Modellierung:**
+- Modellierung der Outlier‑Wahrscheinlichkeit als Funktion der C‑State‑Residency.
+
+**Community-Beiträge:**
+- Template‑Bereitstellung im Trace‑Repository für Replikations‑Experimente.