From b9db7732e3efee3668a9005bd9d29e65e9d64dcd Mon Sep 17 00:00:00 2001 From: Mika Date: Tue, 16 Dec 2025 11:04:00 +0000 Subject: [PATCH] Add unit_tests/README.md --- unit_tests/README.md | 229 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 unit_tests/README.md diff --git a/unit_tests/README.md b/unit_tests/README.md new file mode 100644 index 0000000..7b019af --- /dev/null +++ b/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.