bpf_offset_analysis/bpf_instrumentation/README.md

# Dokumentation der eBPF-Instrumentierung zur Analyse des konstanten Offset-Verhaltens in Clocksource-Traces

## Purpose

Dokumentation der eingesetzten eBPF-Instrumentierung zur Analyse und Reproduktion eines konstanten Offsets von 1,111 s in Kernel-Trace-Daten.

**Problemstellung:** In BPF-Trace-Daten wurde ein konstanter ≈1,111 s‑Offset beobachtet. Ziel ist, die Quelle dieses Offsets innerhalb des Kernelzeitpfads nachzuweisen.

**Ziele:**
- Erfassung präziser Traces für do_clocksource_switch, read und baseline_recalc
- Identifizierung des Zeitabschnitts, in dem der konstante Offset entsteht
- Validierung durch Vergleich von Host und VM mit GPS‑1PPS als Referenz

## Kontext & Hintergrund

300 Runs pro Session, high-resolution time_ns-Timestamps und GPS‑1PPS‑Referenzsignale; Traces gesammelt mit eBPF-Probes an Kernel‑Funktionen.

**Gruppierung:**
- Hostsystem
- virtuelle Maschine (KVM)

**Trace-Metadaten / zusätzliche Tags:**
- Session-ID
- Probe timestamps
- Delta-Chains (Entry→first_read, first_read→baseline_recalc)

**Domänenkontext:**
- Kernel-Timing
- Clocksource-Mechanismus
- eBPF-Tracing
- Zeitabweichungsdiagnose

**Outlier-Definition:**
- Methode: Standardabweichung der Delta-Kette
- Beschreibung: Runs mit mehr als ±3σ Abweichung vom Median gelten als Ausreißer und werden verworfen.
- Metrik: Δ(do_clocksource_switch_entry → first_read)

**Motivation:**
- Reproduzierbarkeit der Zeitpfade zwischen Host und VM sicherstellen
- Verifikation der Stabilität von eBPF gegenüber kprobe-basierten Messungen
- Eingrenzen, ob Scheduling oder Virtualisierung den Offset verursacht

## Methode / Spezifikation

**Übersicht:**
- Erfassung der Traces mittels eBPF entry/exit‑Probes an do_clocksource_switch, clocksource->read() und baseline_recalc
- Auswertung mit Python-Skript trace_agg.py zur Bildung von Delta‑Ketten
- Vergleich der Host‑ und VM‑Messungen für Stabilität und Offsetverhalten

**Algorithmen / Verfahren:**
- Zeitstempelung aller Probes mit time_ns
- Berechnung von Δ(entry→first_read) und Δ(first_read→baseline_recalc)
- Bestimmung von Median und Varianz pro Session
- Bootstrap‑Resampling über 300 Runs zur Stabilitätsanalyse

### Bootstrap-Übersicht

Nichtparametrisches Bootstrap über Run‑Mittelwerte, 300 Stichproben pro Umgebung.

**Zielgrößen:**
- Median‑Stabilität
- Varianz‑Abschätzung
- Konfidenzintervalle der Delta‑Kette

### Resampling-Setup

- Hostsystem
- VM (KVM)

**Stichprobeneinheit:** Einzelne Trace‑Sessions mit vollständiger Delta‑Kette

**Resampling-Schema:**
- Bootstrap mit Zurücklegen
- B=500 Wiederholungen

**Konfidenzintervalle:**
- Niveau: 0.95
- Typ: Percentile Bootstrap CI
- Ableitung: Quantilbasiert aus resample‑Verteilung

### Abgeleitete Effektgrößen

**Risk Difference (Differenz der Raten):**
- Definition: Nicht zutreffend für zeitkontinuierliche Metriken

**Risk Ratio:**
- Definition: Nicht relevant — es wird kein Dichotomie‑Outcome analysiert

### C-State-Kontrolle

**Ziel:** Überprüfung, ob CPU‑Schlafzustände (C‑States) den Offset beeinflussen.

**Vorgehen:**
- Tests mit intel_idle.max_cstate=1 auf Host und VM
- Vergleich der Δ(entry→first_read)‑Verteilungen
- Bewertung der Varianzänderung bei konstant bleibendem Median

## Input / Output

### Input-Anforderungen

**Hardware:**
- x86_64 Hostsystem mit aktivierbarem KVM
- GPS‑1PPS‑Signalquelle

**Software:**
- Linux Kernel ≥5.x mit eBPF-Unterstützung
- bcc/eBPF‑Toolchain
- Python ≥3.8 mit Pandas/Numpy

**Konfiguration:**
- root-Zugriff für eBPF‑Probes
- Symbolzugriff auf Kernel‑Funktionen
- synchrone System‑Clocks (chronyd oder ptp4l)

### Erwartete Rohdaten

**Felder pro Run:**
- timestamp_ns
- probe_name
- session_id
- cpu_id
- delta_chain_id

**Formatbeispiele:**
- 171223.534912180 do_clocksource_switch_entry
- 171224.645912321 first_read

**Trace-Daten:**
- Format: CSV oder JSON‑Lines mit Nanosekundenauflösung
- Hinweis: Jede Kette wird in der Aggregationsstufe zu einer Delta‑Kombination (entry→first_read etc.) verdichtet.

### Analyse-Ausgaben

**Pro Gruppe / pro Governor:**
- Median‑Δ
- Standardabweichung
- Bootstrap‑Konfidenzintervall

**Vergleichsausgaben:**
- Hostsystem vs VM

- C-State-Korrelation: Negativ, keine signifikante Abhängigkeit zum Offset erkannt.
- Trace-Muster: Stabile 1,111 s‑Kette in beiden Umgebungen; kein Anstieg der Varianz außer in I/O‑Phasen.

## Workflow / Nutzung

**Analyse-Workflow:**
- eBPF‑Probes deployen (entry/exit‑Hooks an Ziel‑Funktionen)
- Traces aufnehmen über 300 Runs pro Umgebung
- trace_agg.py ausführen zur Delta‑Berechnung
- Ergebnisse aggregieren und mit GPS‑1PPS synchronisieren
- Bootstrap‑Analyse und Varianzbewertung durchführen

### Trace-Template-Anforderungen

**Ziel:** Sicherstellung einheitlicher Trace‑Struktur für Host und VM.

**Erforderliche Tags & Metadaten:**
- session_id
- probe_name
- timestamp_ns
- cpu_id

**trace-cmd-Setup:**
- BPF‑Skripte mit sudo ausführen
- BPF‑Ringbuffergröße auf ≥64 MB einstellen
- Zeitsynchronisation zwingend per NTP/PPS

**Run-Design für Contributors:**
- Mindestens 300 vollständige Runs pro Testfall
- VM‑Konfiguration dokumentieren (CPU, Scheduler, Kernel‑Version)
- Aggregationsergebnisse als Histogramneinträge exportieren

## Interpretation & erwartete Ergebnisse

**Kernbefunde:**
- Konstanter Offset von 1,111 s zwischen entry und erstem read unabhängig von Umgebung
- Erhöhte Stabilität durch eBPF gegenüber kprobe‑basierter Messung
- C‑State‑Verhalten hat keinen Einfluss auf den Offset

**Implikationen für Experimente:**
- Die Hauptlatenz entsteht vor dem ersten clocksource->read(), wahrscheinlich im Scheduler‑ oder KVM‑Entry‑Pfad
- Weitere Tracepunkte erforderlich zur genauen Lokalisierung

**Planungsziel:**
- Ziel: Isolation des Prozesses, der den konstanten Offset verursacht.
- Vorgehen:
  - Ausweitung der BPF‑Probes auf scheduler_wake, hrtimer_expire, kvm_entry/kvm_exit
  - Einführung per‑chain‑Histogramme in trace_agg.py
  - Analyse mit mindestens 500 Runs unter identischen Bedingungen

## Limitationen & Fallstricke

**Datenbezogene Limitationen:**
- Mögliche Ungenauigkeit bei nicht synchronisierten Host‑VM‑Clocks
- Abhängigkeit von Verfügbarkeit der Kernel‑Symbole

**Bootstrap-spezifische Limitationen:**
- Bootstrap‑CI ungenau bei geringer Run‑Zahl (<100)
- Nichtparametrische Annahme kann systematische Zeitversätze nicht kompensieren

**Kausalität & Generalisierbarkeit:**
- Beobachtete Latenz kann host‑spezifisch sein
- Ergebnisse nicht zwangsläufig auf Nicht‑KVM‑Setups übertragbar

**Praktische Fallstricke:**
- Overhead durch eBPF‑Instrumentation kann marginale Zeitverschiebung erzeugen
- Unzureichende PPS‑Verbindung verfälscht Referenzalignment

## Nächste Schritte & Erweiterungen

**Geplante Experimente:**
- Einführung weiterer Probes für scheduler_wake, hrtimer_expire, kvm_entry, kvm_exit
- Erweiterung um IRQ‑ und Softirq‑Pfade

**Analyseziele:**
- Validierung, ob Scheduling‑Latenz den Offset vollständig erklärt
- Quantifizierung der Interferenz zwischen Host und VM

**Regression & Modellierung:**
- Bootstrap‑Regression zur Modellierung des Einflusses einzelner Pfadsegmente
- Vergleich mit analytischer Latenz aus Tracegraph‑Modellen

**Community-Beiträge:**
- Tests auf unterschiedlichen KVM‑/QEMU‑Umgebungen durch Community
- Bereitstellung von Histogrammen kvm_entry→first_read zur Vergleichanalyse