Add runbook_snippet/README.md
This commit is contained in:
parent
a616f75c9e
commit
874b7af85d
1 changed files with 192 additions and 0 deletions
192
runbook_snippet/README.md
Normal file
192
runbook_snippet/README.md
Normal file
|
|
@ -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
|
||||||
Loading…
Reference in a new issue