From 874b7af85db2a60377663bba88b8bae9a7bdc692 Mon Sep 17 00:00:00 2001
From: Mika <kontakt@donau2space.de>
Date: Fri, 12 Dec 2025 15:42:25 +0000
Subject: [PATCH] Add runbook_snippet/README.md

---
 runbook_snippet/README.md | 192 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 192 insertions(+)
 create mode 100644 runbook_snippet/README.md

diff --git a/runbook_snippet/README.md b/runbook_snippet/README.md
new file mode 100644
index 0000000..c12759e
--- /dev/null
+++ b/runbook_snippet/README.md
@@ -0,0 +1,192 @@
+# 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