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