Add trace_agg_tests/README.md

trace_agg_tests/README.md

@@ -0,0 +1,186 @@
+# Unit-Test-Dokumentation für trace_agg.py
+
+## Purpose
+
+Validierung der Korrektheit und Stabilität der Aggregationslogik in trace_agg.py durch gezielte Unit-Tests.
+
+**Problemstellung:** Früherer Code führte zu fehlerhaften Summen durch nachgelagerte Filterung statt vorgelagerte Filterung vor der Aggregation.
+
+**Ziele:**
+- Sicherstellen, dass Filterung und Aggregation korrekt angewendet werden.
+- Vermeidung von Zähldifferenzen bei Event-Summation.
+- Vorbereitung der Integration in die CI-Testpipeline.
+
+## Kontext & Hintergrund
+
+Acht Trace-Export-Dateien mit durchschnittlich 62 clocksource-Events pro Datei.
+
+**Gruppierung:**
+- clocksource-events
+- tracefiles
+
+**Trace-Metadaten / zusätzliche Tags:**
+- Eventnamen
+- Timestamp
+- CPU-ID
+
+**Domänenkontext:**
+- Performance-Tracing
+- Systemanalyse
+- Event-Aggregation
+
+**Motivation:**
+- Sicherstellung reproduzierbarer Ergebnisse im Analyse-Workflow.
+- Erhöhung der Zuverlässigkeit vor CI-Merge und automatisierten Resampling-Prozessen.
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Unit-Tests validieren die korrekte Funktionsweise der Aggregationspipeline.
+- Tests prüfen Summenbildung und Filterreihenfolge.
+- Referenzwert: 496 Events als erwartetes Gesamtergebnis nach korrekter Filterung.
+
+**Algorithmen / Verfahren:**
+- Setup von acht repräsentativen Trace-Dateien.
+- Filterung der Events vor Aggregation.
+- Überprüfung der Summenbildung nach groupby() und sum().
+- Abgleich der aggregierten Ergebnisse mit erwarteten Zählwerten.
+
+### Bootstrap-Übersicht
+
+Geplante automatisierte CI-Ausführung mit Sample-Traces im Bootstrap-Modus.
+
+**Zielgrößen:**
+- Automatisierte Regressionserkennung
+- Stabilitätsprüfung
+
+### Resampling-Setup
+
+- clocksource
+
+**Stichprobeneinheit:** Trace-Datei
+
+**Resampling-Schema:**
+- Randomisierte Wiederholung der CSV-Samples zur Stabilitätsprüfung
+
+**Konfidenzintervalle:**
+- Niveau: 0.95
+- Typ: bootstrap
+- Ableitung: automatisiert im CI-Job berechnet
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- Standard-x86-Testumgebung
+- CI-Runner mit Python 3.x
+
+**Software:**
+- Python 3.x
+- pytest
+- pandas
+
+**Konfiguration:**
+- Pfad zu Test-Traces konfigurierbar über Umgebungsvariable TRACE_SRC
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- timestamp
+- event
+- cpu_id
+- value
+
+**Formatbeispiele:**
+- 2024-04-01T10:22:33Z,clocksource,0,12345
+
+**Trace-Daten:**
+- Format: CSV
+- Hinweis: Traces mit variabler Länge, aber konstantem event-schema
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- Summe pro Eventtyp
+- Validierungsstatus (Pass/Fail)
+
+**Vergleichsausgaben:**
+- pre_fix vs post_fix
+  - Δ: −0.6%
+  - CI(Δ): [−1.2%, 0.0%]
+  - RR: 0.993
+  - CI(RR): [0.986, 1.0]
+  - Tests: nicht berechnet, Vergleich deterministisch
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Trace-Daten in Testverzeichnis kopieren.
+- Unit-Tests mit pytest ausführen.
+- Ergebnisvalidierung anhand erwarteter Summen.
+- Optional: CI-Integration für automatisierte Testläufe.
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Automatisierte Prüfung der Aggregationslogik für clocksource-Events.
+
+**Erforderliche Tags & Metadaten:**
+- event=clocksource
+- cpu_id
+- timestamp
+
+**trace-cmd-Setup:**
+- tracer-cmd record -e clocksource
+- export als CSV vor Testlauf
+
+**Run-Design für Contributors:**
+- Bereitstellen kleiner Trace-Sets (≤10 Dateien) zur Validierung von Aggregationspfaden.
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Fehlerhafte Summierung durch falsche Filterposition behoben.
+- Ergebnisse stabil und reproduzierbar über alle Test-Traces.
+
+**Implikationen für Experimente:**
+- trace_agg.py kann nun als stabil eingestuft werden.
+- Basis für fortgeschrittenes CI-Bootstrap-Testing geschaffen.
+
+**Planungsziel:**
+- Ziel: Validierte Basisversion zur Integration in automatisierte Langzeittests.
+- Vorgehen:
+  - Integration in CI über täglichen Trace-Testlauf.
+  - Erweiterung des Testumfangs auf C-State-Vergleiche.
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Begrenzte Testdatenmenge (acht Traces) kann seltene Eventtypen unberücksichtigt lassen.
+
+**Bootstrap-spezifische Limitationen:**
+- Bootstrap-Auswertung geplante Erweiterung, aktuell noch manuell.
+
+**Kausalität & Generalisierbarkeit:**
+- Test validiert Logik, nicht Performance oder Laufzeitverhalten unter hoher Last.
+
+**Praktische Fallstricke:**
+- Ungenaue Trace-Dateipfade führen zu Testfehlern.
+- Nicht deterministische Eventreihenfolge kann zu instabilen Tests führen, wenn Sortierung fehlt.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Integration des Fixes in CI-Pipeline mit automatisiertem Bootstrap-Testlauf.
+- Vergleich C0/C1/Cx-State-Auswertungen über 24-Stunden-Datensammlungen.
+
+**Analyseziele:**
+- Quantifizierung von Aggregationsabweichungen über mehrere Runs.
+- Automatische Regressionserkennung durch Resampling.
+
+**Regression & Modellierung:**
+- Bootstrap-basierte Stabilitätsmodelle zur Erkennung von Event-Drift.
+
+**Community-Beiträge:**
+- Bereitstellung zusätzlicher Trace-Datensätze zur Validierung des Tools.
+- Erfahrungsberichte zu Testautomation im CI-Kontext.