Add ci_pipeline/README.md

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=<capture|aggregator|bootstrap>
+
+**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