From 81aab1da79c8ac0c706c1f867f2cbc922107ec30 Mon Sep 17 00:00:00 2001
From: Mika <kontakt@donau2space.de>
Date: Wed, 10 Dec 2025 14:36:42 +0000
Subject: [PATCH] Add ci_yaml_fix/README.md

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

diff --git a/ci_yaml_fix/README.md b/ci_yaml_fix/README.md
new file mode 100644
index 0000000..d398e06
--- /dev/null
+++ b/ci_yaml_fix/README.md
@@ -0,0 +1,144 @@
+# Korrektur der CI-YAML-Konfiguration für persistente Artefaktspeicherung und konsistente Runner-Zuordnung
+
+## Purpose
+
+Dokumentation der Anpassungen an der CI-YAML-Datei zur Vermeidung fehlerhafter Artefaktpfade und inkorrekter Runner-Labels in der Baseline-Rekalibrierungsumgebung.
+
+**Problemstellung:** Im ursprünglichen CI-Setup wurden Artefakte temporär lokal gespeichert, da der Aggregator-Job fälschlicherweise als Capture-Runner gelabelt war.
+
+**Ziele:**
+- Sicherstellung korrekter Runner-Label-Zuordnung zwischen Capture- und Aggregator-Jobs
+- Vermeidung lokaler statt persistenter Artefaktablagen
+- Validierung der YAML-Änderungen durch Probebetrieb mit stratified sampling
+
+## Kontext & Hintergrund
+
+CI-Läufe mit 240 Samples, verteilt auf 4 Capture- und 1 Aggregator-Runner, erzeugt durch trace-cmd mit clocksource_switch und GPS-1PPS als Referenz.
+
+**Gruppierung:**
+- Capture
+- Aggregator
+
+**Trace-Metadaten / zusätzliche Tags:**
+- Runner-Label
+- Artefaktpfad
+- Quota-Definition
+
+**Domänenkontext:**
+- Kernel-Zeitmessung mittels clocksource_switch
+- Baseline-Rekalibrierung bei Kernel-Switch
+- Artefaktmanagement in GitLab-CI
+
+**Motivation:**
+- Reduktion des ≈1,11 s Offsets durch Baseline-Neuberechnung im Kernel
+- Absicherung der CI-Artefaktverwaltung vor fehlerhafter Labelung
+- Herstellung reproduzierbarer Testbedingungen für Zeitreihen-Traces
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Validierung des Kernel-Verhaltens nach Aktivierung der baseline_recalc-on-switch Option
+- Korrektur und Inspektion der CI-YAML-Konfiguration für Job-Label- und Artefaktpfaddefinition
+- Durchführung eines Probebetriebs mit 240 Proben zur Überprüfung der Artefaktverteilung
+
+**Algorithmen / Verfahren:**
+- Labelkorrektur: Aggregator-Job → Label 'aggregator' statt 'capture'
+- Artefakt-Pfaddefinition auf persistenten Speicher korrigiert
+- Quota-Verifizierung für stabile Artefaktspeicherung
+- Unit-Test-Ausführung von trace_agg.py zur Validierung
+
+## Input / Output
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- runner_label
+- artefakt_path
+- quota_status
+- trace_ref
+
+**Formatbeispiele:**
+- capture_01,/mnt/persist/art_2024-06-10.ok,valid,trace_abc123
+
+**Trace-Daten:**
+- Format: trace-cmd output with timestamp alignment via GPS-1PPS
+- Hinweis: Wird verwendet zur Kreuzvalidierung der Baseline-Neuberechnung.
+
+### Analyse-Ausgaben
+
+**Vergleichsausgaben:**
+- Mini-CI vs Produktions-CI
+  - Δ: 1.1
+  - CI(Δ): geplant (10k Bootstrap Overnight)
+
+- Trace-Muster: Keine Sprünge in clocksource->read() nach Patch; maximale Abweichung 6 ms.
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- YAML-Validierung mit CI-Lint
+- Probe-Run mit stratified sampling (240 Samples)
+- Review und Merge Request Vorbereitung
+- Überführung in reguläres CI-Pipeline-Schema
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Standardisierung der Tracedaten für inter-Hardware-Vergleich
+
+**Erforderliche Tags & Metadaten:**
+- runner_label
+- clocksource
+- gps_pps_offset
+
+**trace-cmd-Setup:**
+- clocksource_switch aktivieren
+- BPF-kprobe attach
+- 1PPS Signal als Referenz
+
+**Run-Design für Contributors:**
+- Mindestens ein Aggregator, vier Capture-Runner
+- Persistente Artefaktpfade sicherstellen
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Nach YAML-Korrektur keine lokale Artefaktablage mehr
+- Aggregationslauf produziert stabile, vollständige Artefakte
+- Kernel-Patch eliminiert initialen 1.11 s Offset
+
+**Implikationen für Experimente:**
+- CI-Infrastruktur ist geeignet für Replikationsläufe mit GPS-Referenz
+- Fehlerhafte Labelverteilung kann signifikante Artefaktverluste verursachen
+
+**Planungsziel:**
+- Ziel: Planung und Durchführung des 10k Bootstrap-Resampling zur Bestimmung der Abweichungsverteilung
+- Vorgehen:
+  - Automatisierte Analyse über Nacht
+  - Einsammeln von Vergleichstraces über verschiedene Hardwareplattformen
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Off-by-3 Fehler in Aggregationszählung (496 vs. 499)
+- Abhängigkeit von GPS-PPS Stabilität bei Tracerfassung
+
+**Bootstrap-spezifische Limitationen:**
+- Bootstrap-Schätzung abhängig von Stichprobengröße und Runner-Stabilität
+
+**Praktische Fallstricke:**
+- Fehlerhafte Runner-Labels führen zu inkonsistenten Artefaktpfaden
+- Quota-Fehlkonfiguration kann Laufabbrüche verursachen
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Replikationsmessung mit GPS-PPS auf alternativer Hardware
+- Überprüfung der Variablen, die alten Baseline-Wert beibehält
+
+**Analyseziele:**
+- Bootstrap 10k zur Konfidenzintervallschätzung
+- Validierung der Aggregationszählung nach Off-by-3-Fix
+
+**Community-Beiträge:**
+- Freigabe der YAML- und Log-Dateien im Merge Request
+- Einladung zur Trace-Replikation und Ergebnis-Postings