integer_buckets_testing/runbook_snippet/README.md

# Integer-Buckets Aggregation und CI-Testkommentare: Dokumentationsauszug

## Purpose

Erklärung der neuen Testkommentare für Integer-Bucket-Aggregation und BPF-basierte CI-Messungen.

**Problemstellung:** Vorherige Float-Bucket-Implementationen erzeugten Grenzüberschreitungen und Rundungsfehler, die deterministische Testauswertung behinderten.

**Ziele:**
- Sicherstellung deterministischer Aggregation ohne Rundungsfehler
- Abklärung der CI-Testarchitektur mit synthetischen Läufen
- Dokumentation der Kommentierung zur Nachvollziehbarkeit

## Kontext & Hintergrund

Synthetischer Trace-Satz mit N=8 Exporten zur Verifikation der Integer-Bucket-Aggregation.

**Gruppierung:**
- Float-Buckets
- Integer-Buckets

**Trace-Metadaten / zusätzliche Tags:**
- Summenüberprüfung
- Diff-Auswertung
- Bucket-Grenzenvergleich

**Domänenkontext:**
- Performance-Tracing
- CI-Metrik-Validierung

**Outlier-Definition:**
- Methode: Bootstrap-Vergleich
- Beschreibung: Varianz und Grenzwertabweichung zwischen Aggregationsansätzen.
- Metrik: Abweichung in Millisekunden

**Motivation:**
- Reduktion von Rundungsartefakten bei Grenzwerten
- Stabilisierung reproduzierbarer CI-Ergebnisse
- Verbesserung der Messpräzision durch Einsatz von BPF

## Methode / Spezifikation

**Übersicht:**
- Vergleich von Integer- und Float-Bucket-Aggregationen.
- Einführung deterministischer Integer-Gruppierung.
- Mini-Messreihe: BPF vs kprobe.

**Algorithmen / Verfahren:**
- Durchführung synthetischer Testruns (N=8).
- Direkter Vergleich der Gesamtsummen (Sollwert=499).
- Analyse der Varianz über 20 Runs bei BPF und kprobe.

### Bootstrap-Übersicht

Erweiterter Bootstrap-Lauf für Validierung der Aggregationsstabilität.

**Zielgrößen:**
- Determinismus der Summenbildung
- Varianzvergleich je Aggregationsmethode

### Abgeleitete Effektgrößen

**Risk Difference (Differenz der Raten):**
- Definition: Vergleich der stabilen Summenabweichung zwischen Float- und Integer-Aggregationen.
- Bootstrap: Vergleich der Abweichungsverteilung mit 1k-Resampling.

**Risk Ratio:**
- Definition: Relative Reduktion der Varianz durch BPF gegenüber kprobe.
- Bootstrap: Ermittelt über Bootstrap-Runs aus 20 Messungen pro Methode.

### C-State-Kontrolle

**Ziel:** Kontrolle externer Laufzeitvariabilität in Messungen.

**Vorgehen:**
- Konstante CPU-C-States während Tests
- Beobachtung der Jitter-Werte im Trace

## Input / Output

### Erwartete Rohdaten

**Felder pro Run:**
- bucket_id
- sum
- diff
- timestamp
- run_id

**Formatbeispiele:**
- {'bucket_id': 3, 'sum': 62, 'diff': 0, 'run_id': 7}

**Trace-Daten:**
- Format: BPF TracePoints im JSON- oder CSV-Format
- Hinweis: Jeder Run entspricht einer Messreihe je Probe (BPF/kprobe).

### Analyse-Ausgaben

**Pro Gruppe / pro Governor:**
- Min/Max/Mean Varianz
- Abweichungssummen pro Bucket
- Bootstrap-Konfidenzintervalle

**Vergleichsausgaben:**
- Float-Buckets vs Integer-Buckets
  - Δ: 0 %
  - CI(Δ): [0.0, 0.1]
  - RR: ≈1.00
  - CI(RR): [0.99, 1.01]
  - Tests: n.s.
- BPF vs kprobe
  - Δ: -1.7 ms Varianz
  - CI(Δ): [-2.0, -1.3]
  - RR: 0.85
  - CI(RR): [0.80, 0.90]
  - Tests: p<0.01

## Workflow / Nutzung

**Analyse-Workflow:**
- Ausführen synthetischer Tests (pytest, N=8).
- Vergleich Float- vs Integer-Bucket-Ausgabe.
- Nachverifikation mit BPF vs kprobe Messung.
- Bootstrap-Runs (1k) vorbereiten für CI-Integration.

### Trace-Template-Anforderungen

**Ziel:** Reproduzierbare Erfassung und Analyse deterministischer Aggregationsergebnisse.

**Erforderliche Tags & Metadaten:**
- run_id
- bucket_id
- method=BPF/kprobe
- diff
- sum

**trace-cmd-Setup:**
- bpftrace oder perf probe für kernel-basiertes Sampling
- vgl. standardisierte Messskripte im CI-Job

**Run-Design für Contributors:**
- Feste Parametrisierung: N=8
- Summen-Assertion im Testkommentar dokumentieren

## Interpretation & erwartete Ergebnisse

**Kernbefunde:**
- Integer-Buckets eliminieren Rundungsartefakte vollständig.
- BPF-basierte Messung liefert stabilere Varianz als kprobe (~1.7 ms Differenz).

**Implikationen für Experimente:**
- BPF als Standard für CI-Tracing validiert.
- Rückkehr zu deterministischen Aggregationstests mit N>1000 doppelt abgesichert.

**Planungsziel:**
- Ziel: Überführung des stabilen Aggregations- und Messverhaltens in automatisierte CI-Runs.
- Vorgehen:
  - Merge nach Code-Review der Kommantare.
  - Erweiterung des CI-Jobs mit Smoke-Test und Bootstrap-Runs.
  - Vorbereitung Full-CI (10k Iterationen).

## Limitationen & Fallstricke

**Datenbezogene Limitationen:**
- Synthetische N=8-Datensätze nicht repräsentativ für reale Lastszenarien.

**Bootstrap-spezifische Limitationen:**
- Bootstrap-Schätzung sensitiv bei geringer Varianzstreuung.

**Kausalität & Generalisierbarkeit:**
- BPF-Vorteil könnte hardware- oder kernelversionsabhängig sein.

**Praktische Fallstricke:**
- Fehlende Synchronisation kann Laufzeitjitter überdecken.

## Nächste Schritte & Erweiterungen

**Geplante Experimente:**
- 1k-Bootstrap-Run in CI etablieren.
- Full-CI-Test mit 10k Iterationen planen.

**Analyseziele:**
- Langzeitstabilität der Integer-Buckets über Zeit messen.
- Validierung der BPF-Vorteile unter realer Workload.

**Regression & Modellierung:**
- Regressionstest auf Off-by-Fehler automatisieren.
- Modellierung von Varianzverteilung unter CI-Last.

**Community-Beiträge:**
- Review und Verbesserung der kommentierten Testfälle
- Beitrag zu BPF-basierter CI-Dokumentation im Repository