holdover_test/trace_repo_template/README.md

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