Add unit_tests/README.md

unit_tests/README.md

@@ -0,0 +1,229 @@
+# Unit-Test-Anforderungen für EM-Summary-Metriken in trace_agg.py
+
+## Purpose
+
+Validierung und Absicherung der neuen EM-Summary-Felder im trace_agg.py-Skript.
+
+**Problemstellung:** Die Integration der drei neuen EM-Summary-Metriken (peak_amplitude, median_bandpower, crosscorr_with_clockevents) benötigt stabile Unit-Tests zur Gewährleistung funktionaler Korrektheit und numerischer Konsistenz.
+
+**Ziele:**
+- Sicherstellen korrekter Berechnung und Aggregation der EM-Metriken.
+- Überwachung der Integrität und Stabilität der CI bei aktivierten EM-Summaries.
+- Reduktion von Fehlinterpretationen durch fehlerhafte Messwerte oder Parserabweichungen.
+
+## Kontext & Hintergrund
+
+Aggregierte EM-Trace-Summaries pro CI-Run.
+
+**Gruppierung:**
+- CI-Jobs
+- Testläufe
+- Nightly-Runs
+
+**Trace-Metadaten / zusätzliche Tags:**
+- clocksource_switch_offset
+- c_state_distribution
+- board_id
+- measurement_timestamp
+
+**Domänenkontext:**
+- HF-Messung in Embedded-Systemen
+- Anomalieerkennung im CI-Prozess
+- Fehlertolerante Metrikaggregation
+
+**Outlier-Definition:**
+- Methode: statistisch, basierend auf Bootstrap-Sampling der EM-Features
+- Beschreibung: Outlier = Werte oberhalb 97,5. Perzentil im Bootstrap der peak_amplitude über Runs.
+- Metrik: peak_amplitude
+
+**Motivation:**
+- Früherkennung von Hardware-Fehlern über hochfrequente Signale.
+- Reduktion von Mess-Overhead durch Summaries statt Rohtraces.
+- Beibehaltung reproduzierbarer Metriken für Regression-Detection.
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- trace_agg.py berechnet drei EM-Summary-Metriken pro Job.
+- Ein Smoke-Test (N=200) lieferte stabile Werte ±12 % Laufzeitkosten.
+- Unit-Tests prüfen Konsistenz der Aggregation, Grenzwerte und Schema-Kompatibilität.
+
+**Algorithmen / Verfahren:**
+- Berechnung median_bandpower über FFT auf verdichteten Sub-Traces.
+- peak_amplitude als Maximalwert der Feldstärke in Zeitdomäne.
+- crosscorr_with_clockevents über normierte Kreuzkorrelation.
+
+### Bootstrap-Übersicht
+
+Resampling der EM-Summary-Metriken über CI-Runs zur Stabilitätsschätzung.
+
+**Zielgrößen:**
+- Varianz
+- Konfidenzintervall der Mittelwerte
+- Outlier-Rate
+
+### Resampling-Setup
+
+- Nightly-Run
+- Branch-Build
+
+**Stichprobeneinheit:** CI-Lauf (1 Durchgang)
+
+**Resampling-Schema:**
+- Bootstrap mit 1000 Iterationen
+
+**Konfidenzintervalle:**
+- Niveau: 0.95
+- Typ: percentile-based
+- Ableitung: über Bootstrap-Distribution
+
+### Abgeleitete Effektgrößen
+
+**Risk Difference (Differenz der Raten):**
+- Definition: Differenz der Outlier-Anteile zwischen Spacer- und Reference-Jobs.
+- Bootstrap: Resampling der Jobgruppen mit Rekombination
+
+**Risk Ratio:**
+- Definition: Quotient der Outlier-Wahrscheinlichkeiten zweier Gruppen.
+- Bootstrap: Log-Transformation des Verhältnisses zur CI-Schätzung.
+
+### C-State-Kontrolle
+
+**Ziel:** Minimierung systematischer HF-Abweichungen durch CPU-Zustandsvariation.
+
+**Vorgehen:**
+- C-State-Logging pro Run aktivieren.
+- Stratifizierte Resampling-Auswertung zur Isolierung der C-State-Effekte.
+
+## Input / Output
+
+### Input-Anforderungen
+
+**Hardware:**
+- HF-taugliche Messsonde
+- geerdeter Spacer
+- Embedded-Board mit Clocktrace-Signal
+
+**Software:**
+- trace_agg.py >= 2.3
+- Python >= 3.10
+- pytest >= 7.0
+
+**Konfiguration:**
+- EM-Summary-Collection = enabled
+- Schema-Version = v1
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- run_id
+- timestamp
+- peak_amplitude
+- median_bandpower
+- crosscorr_with_clockevents
+
+**Formatbeispiele:**
+- 1234, 2024-05-20T12:03, 0.0021, 0.018, 0.63
+
+**Trace-Daten:**
+- Format: kompakte JSON-Summary pro Run
+- Hinweis: Keine Volltraces in CI; Rohdaten nur On-Demand.
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- Mittelwert
+- Varianz
+- Outlier-Anteil
+- CI-Intervall
+
+**Vergleichsausgaben:**
+- mit Spacer vs ohne Spacer
+  - Δ: -60 % peak_amplitude
+  - CI(Δ): [−58 %; −63 %]
+  - RR: 0.38
+  - CI(RR): [0.34; 0.42]
+  - Tests: p<0.01
+
+- C-State-Korrelation: r≈0.5
+- Trace-Muster: HF-Absenkung stabil bei 0.5 mm Spacer
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Smoke-Test in CI starten (N=200).
+- trace_agg.py-Output prüfen.
+- Unit-Tests mit pytest ausführen.
+- Bootstrap-Auswertung über summary.csv fahren.
+- Bericht erstellen (Metriken + CIs).
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Nachverfolgbarkeit der EM-Zusammenfassung und Schema-Gültigkeit pro Commit.
+
+**Erforderliche Tags & Metadaten:**
+- schema_version
+- run_id
+- board_id
+- clocksource_offset
+- measurement_env
+
+**trace-cmd-Setup:**
+- trace-cmd record --event em_summary_collect
+- sampling_rate = 1/50 runs
+- Speicherung ausschließlich von Summary-Feldern
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- EM-Summaries zeigen starke Korrelation zu HF-Outliers.
+- Spacer-Effekt klar detektierbar über peak_amplitude.
+- Kein Einfluss auf clocksource_offset beobachtet.
+
+**Implikationen für Experimente:**
+- EM-Features als standardisierte Diagnose-Metrik in CI-Frameworks.
+- Einführung versionierter EM-Schema-Definitionen.
+
+**Planungsziel:**
+- Ziel: Langfristige Integration der EM-Signaldaten zur automatisierten Fehlerdiagnose.
+- Vorgehen:
+  - Unit-Tests als Stabilitätsanker des Messpfads.
+  - Bootstrap-CI zur statistischen Vergleichbarkeit der Hardwareläufe.
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Summaries können lokale Peaks glätten und Fehlindikationen liefern.
+- HF-Messrauschen kann Outlier-Erkennung beeinflussen.
+
+**Bootstrap-spezifische Limitationen:**
+- Nichtstationäre Effekte zwischen Nightly-Runs wirken verzerrend.
+- Kleine N pro Gruppe kann CI-Unsicherheit erhöhen.
+
+**Kausalität & Generalisierbarkeit:**
+- Spacer-Effekt nicht zwingend auf andere Boards übertragbar.
+- Fehlende Isolation anderer EM-Störquellen.
+
+**Praktische Fallstricke:**
+- 12 % Laufzeitmehrbelastung in CI zu berücksichtigen.
+- Parserrobustheit bei inkompletten Fields testen.
+- Schema-Version strikt prüfen, um Inkompatibilitäten zu vermeiden.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Kernel-Trace in isolierter VM mit stratifizierten C-States.
+- Vergleich verschiedener EM-Abschirmungen.
+
+**Analyseziele:**
+- Quantifizierung der HF-Störkorrelation mit Systemlatenzen.
+- Ableitung neuer Alert-Thresholds für Regressionsprüfungen.
+
+**Regression & Modellierung:**
+- Aufbau eines Regressionsmodells über EM- und Timing-Metriken.
+- Integration in CI-Pipeline mit adaptiver Schwellenlogik.
+
+**Community-Beiträge:**
+- Review der verpflichtenden EM-Schemafelder.
+- Vorschläge zu Retentionsdauer On-Demand-Rohtraces.
+- Standardisierung von Alert-Thresholds im PR-Template.