powersave_analysis/powersave_logging/README.md

# Dokumentation des Powersave- und C-State-Loggings

## Purpose

Dokumentation der Erfassung und Auswertung von Powersave-Zuständen (C-States) zur Beurteilung des Governor-Effekts und dessen Abhängigkeit von C3-Residency.

**Problemstellung:** Unklar war, ob der Governor-bedingte Jitter aus elektrischen Störungen stammt oder durch Aktivität in tiefen CPU-Schlafzuständen (C3) vermittelt wird. Ziel war, über Logging und Aggregation der C-State-Daten diesen Zusammenhang nachzuweisen.

**Ziele:**
- Präzise Logging- und Analysebasis für C-State-bezogene Outlier-Erkennung schaffen
- Differenzierung von Effekten zwischen normalem und limitiertem Powersave-Modus ermöglichen
- Reproduzierbare CSV-Exporte mit allen relevanten Trace-Feldern bereitstellen

## Kontext & Hintergrund

120 Micro-Benchmarks pro Modus (normaler powersave vs. powersave mit C3-Sperre).

**Gruppierung:**
- normal
- restricted

**Trace-Metadaten / zusätzliche Tags:**
- C-State-Residency
- clocksource_switch Events
- Outlier-Flag
- EM-Probe-Daten

**Domänenkontext:**
- CPU-Governor-Analyse
- C-State-Transition-Logging
- BPF-Trace-Datenerhebung
- Energiemanagementmessungen

**Outlier-Definition:**
- Methode: Benchmarkabweichung
- Beschreibung: Runs mit signifikant erhöhter Latenz oder Variabilität gegenüber dem Median
- Metrik: Outlier-Rate pro Modus in Prozent

**Motivation:**
- Aufklärung des Zusammenhangs zwischen Governor-Verhalten und C3-Eintritt
- Eliminierung nicht-elektrischer Einflüsse durch kontrolliertes Power-State-Limit

## Methode / Spezifikation

**Übersicht:**
- Vergleich zweier Powersave-Konfigurationen mit identischer Benchmark-Last.
- Erfassung von C-State-Residencies, clocksource_switch-Ereignissen und EM-Traces.
- Bootstrap-Auswertung zur Bestimmung der Vertrauensintervalle und Signifikanz.

**Algorithmen / Verfahren:**
- pro Modus 120 Benchmarks sammeln
- C-State-Residency summieren und Outlier markieren
- Bootstrap-Resampling mit 10.000 Iterationen, 95%-Konfidenzintervall
- Berechnung der Differenz in Outlier-Proportionen und Risk Ratio

### Bootstrap-Übersicht

Non-parametrisches Resampling zur Abschätzung der Schwankung der Outlier-Rate.

**Zielgrößen:**
- Differenz der Outlier-Anteile
- Risk Ratio zwischen Modi

### Resampling-Setup

- normal
- restricted

**Stichprobeneinheit:** Benchmark-Run

**Resampling-Schema:**
- 10000-faches Resampling pro Modus

**Konfidenzintervalle:**
- Niveau: 0.95
- Typ: percentile
- Ableitung: durch Bootstrap-Verteilung

### Abgeleitete Effektgrößen

**Risk Difference (Differenz der Raten):**
- Definition: Prozentuale Differenz der Outlier-Raten zwischen beiden Modi.
- Bootstrap: Zur Abschätzung der Unsicherheit des Effekts.

**Risk Ratio:**
- Definition: Verhältnis der Outlier-Wahrscheinlichkeit im normalen gegenüber restringiertem Modus.
- Bootstrap: 95%-CI aus Bootstrap-Sampling.

### C-State-Kontrolle

**Ziel:** Einfluss tiefer C-States auf den Governor-Effekt prüfen.

**Vorgehen:**
- C3-Zugriff über Kernelparameter intel_idle.max_cstate=1 einschränken
- Residency-Verteilungen vergleichen
- Auswirkung auf clocksource_switch-Frequenz beobachten

## Input / Output

### Input-Anforderungen

**Hardware:**
- Intel-basierte CPU mit Idle-States bis C3
- EM-Probe
- Referenz-Benchmark-Rig

**Software:**
- Linux-Kernel mit BPF-Support
- trace_agg.py
- Shell-/Python-Umgebung

**Konfiguration:**
- intel_idle.max_cstate=1 oder höher
- aktive BPF-Traces auf clocksource_switch

### Erwartete Rohdaten

**Felder pro Run:**
- run_id
- mode
- outlier_flag
- c0_time
- c1_time
- c3_time
- clocksource_switch_count
- em_trace_sum

**Formatbeispiele:**
- normal,42,False,81.2,15.4,3.4,15,0.98

**Trace-Daten:**
- Format: CSV aus trace_agg.py
- Hinweis: Spaltenbezeichner müssen exakt dem im Repository definierten Schema folgen

### Analyse-Ausgaben

**Pro Gruppe / pro Governor:**
- C3-Residency-Mittelwert
- Outlier-Anteil
- CI-Grenzen

**Vergleichsausgaben:**
- normal vs restricted
  - Δ: -18.3%
  - CI(Δ): [3.1, 11.8]
  - RR: ≈3.7
  - CI(RR): [2.0, 8.4]
  - Tests: ≈0.002

- C-State-Korrelation: starke positive Korrelation zwischen hoher C3-Residency und Outlier-Häufigkeit
- Trace-Muster: clocksource_switch-Events korrelieren mit Outlier-Phasen

## Workflow / Nutzung

**Analyse-Workflow:**
- Benchmarks ausführen unter normalem und limitiertem Powersave
- Traces erfassen (BPF, EM, C-State)
- trace_agg.py zur Aggregation verwenden
- Bootstrap-Analyse der Resultate ausführen
- Vergleich der Resultate dokumentieren

### Trace-Template-Anforderungen

**Ziel:** Standardisierte Traces für Replikation und Vergleich ermöglichen.

**Erforderliche Tags & Metadaten:**
- mode
- run_id
- c_state_times
- outlier_flag
- clocksource_switch_count

**trace-cmd-Setup:**
- bpftrace -e 'tracepoint:power:cpu_idle { ... }'
- Aufzeichnungszeit synchronisieren

**Run-Design für Contributors:**
- mindestens 100 Testläufe pro Konfiguration
- identische Benchmark-Workload verwenden

## Interpretation & erwartete Ergebnisse

**Kernbefunde:**
- Outlier-Rate sinkt drastisch, sobald C3 gesperrt ist.
- C3-Residency korreliert mit Jitter-Ausreißern.
- clocksource_switch-Events treten im eingeschränkten Modus kaum auf.

**Implikationen für Experimente:**
- Governor-Verhalten stark durch tiefe Idle-States beeinflusst.
- Reproduktion ohne elektrische Einflussfaktoren möglich.
- C-State-Begrenzung als Kontrollvariable für Governor-Vergleiche geeignet.

**Planungsziel:**
- Ziel: Nachweis des CPU-internen Ursprungs des Governor-Effekts.
- Vorgehen:
  - systematische Sperrung von C3
  - Erhebung und Aggregation aller Trace-Daten mit trace_agg.py

## Limitationen & Fallstricke

**Datenbezogene Limitationen:**
- Outlier-Definition abhängig von Benchmark-Charakteristik
- BPF-Trace-Zeitauflösung begrenzend für feine Latenzen

**Bootstrap-spezifische Limitationen:**
- Annahmen zu Unabhängigkeit zwischen Runs erforderlich
- geringe Stichprobenzahlen können CI verbreitern

**Kausalität & Generalisierbarkeit:**
- Ergebnisse primär für Intel Idle-Governor gültig
- Übertragbarkeit auf ARM- oder AMD-Plattformen unbestätigt

**Praktische Fallstricke:**
- unkonsistente Trace-Formate verhindern Aggregation
- fehlende Metadata (Spacer, Hardware) limitieren Vergleichbarkeit

## Nächste Schritte & Erweiterungen

**Geplante Experimente:**
- Langzeitvergleich über 24 h zwischen performance und powersave+C0/C1
- Spacer-Sweep-Test (0 → 0,5 → 1 mm)
- Unit-Test-Integration für trace_agg.py

**Analyseziele:**
- Validierung der Stabilität des Governor-Clocksource-Offsets
- Quantifizierung der Outlier-Stabilität über Zeit

**Regression & Modellierung:**
- Modellierung der C-State-Auswirkungen auf Latenzverteilung
- Vorbereitung linearer Mixed-Effects-Modelle für Governor-Zustände

**Community-Beiträge:**
- Einreichen von Remote-Traces unter intel_idle.max_cstate=1
- Bereitstellung von Hardware- und Spacer-Metadaten zur Meta-Analyse