From 5a8b776ec745cffc3cc33e21b75a42bf70046187 Mon Sep 17 00:00:00 2001 From: Mika Date: Tue, 9 Dec 2025 14:56:51 +0000 Subject: [PATCH] Add ci_pipeline/README.md --- ci_pipeline/README.md | 230 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 ci_pipeline/README.md diff --git a/ci_pipeline/README.md b/ci_pipeline/README.md new file mode 100644 index 0000000..b8a71af --- /dev/null +++ b/ci_pipeline/README.md @@ -0,0 +1,230 @@ +# Mini-CI Probelauf mit stratified sampling, Runner-Split und Bootstrap-Checks + +## Purpose + +Technische Dokumentation des Mini-CI-Probelaufs zur Validierung von Bootstrap-Konsistenz und Laufzeitstabilität im Vergleich zu einem Single-Runner-Ansatz. + +**Problemstellung:** Vor dem Full-Run sollte überprüft werden, ob das geplante CI-Design mit stratified sampling und getrennten Runnern zuverlässig reproduzierbare Bootstrap-Ergebnisse liefert. + +**Ziele:** +- Nachweis der Stabilität von Bootstrap-Konfidenzintervallen bei unterschiedlichen CPU-State-Konfigurationen +- Evaluation des Runner-Splits (capture, aggregator, bootstrap) +- Konfiguration eines skalierbaren Mini-CI-Designs für experimentelle Performance-Analysen + +## Kontext & Hintergrund + +Jedes CI-Job-Run enthält Traces und Outlier-Raten, getrennt nach CPU-State-Profilen ('powersave' und 'performance'). + +**Gruppierung:** +- CPU-State-Gruppe +- Runner-Typ +- CI-Job + +**Trace-Metadaten / zusätzliche Tags:** +- C-State-Tags +- Zeilenendungsformat +- Trace-Aggregator-Ausgabe + +**Domänenkontext:** +- Continuous Integration +- Performance Tracing +- Bootstrap-Statistik +- System Benchmarks + +**Outlier-Definition:** +- Methode: Bootstrap-Schätzung je Gruppe +- Beschreibung: Outlier-Rate basierend auf Job-Zeitverteilung pro CPU-State. +- Metrik: Prozentuale Abweichung der Outlier-Rate (pp) + +**Motivation:** +- Reduktion der Streuung bei Bootstrap-Ergebnissen +- Getrennte Steuerung und Resampling zur Reduktion von Laufzeitvariabilität +- Validierung der CI-Tauglichkeit für lange Bootstrap-Läufe + +## Methode / Spezifikation + +**Übersicht:** +- 10 Replikate je Run mit N≈240 pro Job +- Stratifizierung in 'powersave' und 'performance' +- Parallele Capture-Runner, zentraler Aggregator, separater Bootstrap-Runner + +**Algorithmen / Verfahren:** +- Stratifiziertes Sampling nach CPU-State +- Aggregation und Normalisierung der Traces +- Bootstrap-Resampling mit 1000 Wiederholungen pro Probe + +### Bootstrap-Übersicht + +Nichtparametrisches Resampling zur Schätzung stabiler Konfidenzintervalle der Outlier-Rate. + +**Zielgrößen:** +- Outlier-Rate +- Intervallbreite +- Risikoquotient + +### Resampling-Setup + +- 'powersave' +- 'performance' + +**Stichprobeneinheit:** einzelner CI-Job-Run + +**Resampling-Schema:** +- 1000 Bootstrap-Resamples je Gruppe + +**Konfidenzintervalle:** +- Niveau: 0.95 +- Typ: percentile CI +- Ableitung: empirisch aus Resampling-Verteilung + +### Abgeleitete Effektgrößen + +**Risk Difference (Differenz der Raten):** +- Definition: Differenz der Outlier-Raten zwischen CPU-State-Gruppen in Prozentpunkten. +- Bootstrap: Schätzung des CI der Differenz via Bootstrap der Gruppenmittelwerte. + +**Risk Ratio:** +- Definition: Quotient der Outlier-Raten zwischen 'performance' und 'powersave'. +- Bootstrap: Verteilung des Quotienten aus resampleten Gruppenraten. + +### C-State-Kontrolle + +**Ziel:** Sicherstellung konsistenter Zuordnung von Traces zu CPU-State-Labels. + +**Vorgehen:** +- Normalisierung der C-State-Tags im Aggregator +- Zeilenendungs-Normalisierung zur Vermeidung von Trace_Mismatch + +## Input / Output + +### Input-Anforderungen + +**Hardware:** +- CI-Runner mit CPU-State-Steuerung +- Oszilloskoptracing-fähige Umgebung + +**Software:** +- CI-System (GitLab CI oder GitHub Actions) +- Python/R Statistikbibliothek +- Trace-Aggregator + +**Konfiguration:** +- stratified_sample_size=240 +- capture_parallel=4 +- aggregator_mode=singleton +- bootstrap_runs=1000 (Quick-Check) / 10000 (Full-Run) +- job_timeouts=900s pro Run + +### Erwartete Rohdaten + +**Felder pro Run:** +- job_id +- cpu_state +- runtime_s +- outlier_flag +- trace_path + +**Formatbeispiele:** +- {'job_id': 1, 'cpu_state': 'powersave', 'runtime_s': 814, 'outlier_flag': false} + +**Trace-Daten:** +- Format: JSON/CSV mit Zeit- und State-Feldern +- Hinweis: Zeilenenden müssen normalisiert sein. + +### Analyse-Ausgaben + +**Pro Gruppe / pro Governor:** +- mean_runtime +- outlier_rate +- ci_width_pp + +**Vergleichsausgaben:** +- powersave vs performance + - Δ: 1.1 + - CI(Δ): [0.7;1.5] + - RR: 0.97 + - CI(RR): [0.93;1.02] + +- C-State-Korrelation: Pearson-Korrelation zwischen Outlier-Rate und C-State-Verteilung pro Runner +- Trace-Muster: Erkennung von systematischen Trace-Mismatches nach Normalisierung 0% + +## Workflow / Nutzung + +**Analyse-Workflow:** +- Trigger eines Mini-CI-Runs mit definierten Stratified-Jobs +- Paralleles Capture der Traces (4 Runner) +- Zentrale Aggregation und Normalisierung +- Bootstrap-Resampling und CI-Auswertung +- Vergleich mit vorherigen Runs (Single-Runner-Referenz) + +### Trace-Template-Anforderungen + +**Ziel:** Reproduzierbare Traces mit eindeutigen CPU-State-Tags + +**Erforderliche Tags & Metadaten:** +- cpu_state +- timestamp +- runner_type +- trace_source + +**trace-cmd-Setup:** +- --normalize-line-endings +- --tag-cstate +- --runner-label= + +**Run-Design für Contributors:** +- je 10 Replikate pro State-Klasse +- N=240 pro Gruppe +- Runner-Labels nach Typ zuweisen + +## Interpretation & erwartete Ergebnisse + +**Kernbefunde:** +- Stratifiziertes Mini-CI-Design bietet stabile Bootstrap-CIs (Breite ≈1.1pp) +- Runner-Split reduziert Streuung signifikant gegenüber Single-Runner-Setup +- Bottleneck liegt im Aggregator und Bootstrapping, nicht im Tracing selbst + +**Implikationen für Experimente:** +- Runner-Trennung ist für Langzeit-Bootstrap-Läufe sinnvoll +- Job-Design mit N≈240 ist statistisch hinreichend und ressourcenschonend + +**Planungsziel:** +- Ziel: Planung eines Full-Runs über 24h +- Vorgehen: + - Erhöhung der Bootstrap-Wiederholungen auf 10k + - Überwachung der Drift (1PPS) im Selftest + +## Limitationen & Fallstricke + +**Datenbezogene Limitationen:** +- Empfindlich gegenüber falscher CPU-State-Zuordnung +- Trace-Mismatch kann CI-Breite verfälschen + +**Bootstrap-spezifische Limitationen:** +- Bei niedriger N kann die CI-Schätzung instabil werden +- Starker Einfluss von Gruppenungleichgewicht auf Risk-Ratio + +**Kausalität & Generalisierbarkeit:** +- Ergebnisse beschränken sich auf Mini-CI-Setups mit ähnlichem Runner-Layout +- Keine Übertragbarkeit auf heterogene Multi-Host-Szenarien + +**Praktische Fallstricke:** +- 6h-Job-Limits erfordern robustes Artifact-Handling +- Langlaufende CI-Systeme sind abhängig von zuverlässigen Runnern und Storage + +## Nächste Schritte & Erweiterungen + +**Geplante Experimente:** +- Full-Run mit 10k Bootstrap-Resamples über 24h auf dediziertem Runner-Pool +- Drift-Vergleich mittels 1PPS-Selbsttest + +**Analyseziele:** +- Untersuchung der Stabilität über Langzeitintervalle +- Korrelation Bootstrap-Varianz zu Trace-Dauer + +**Regression & Modellierung:** +- Modellierung der CI-Breite als Funktion der Bootstraps und der CPU-State-Varianz + +**Community-Beiträge:** +- Vergleich GitHub vs. GitLab CI für lange Jobs +- YAML-Konfigurationsreview durch andere CI-Setups