Add unit_tests/README.md
This commit is contained in:
parent
76e6a9bbc4
commit
b9db7732e3
1 changed files with 229 additions and 0 deletions
229
unit_tests/README.md
Normal file
229
unit_tests/README.md
Normal file
|
|
@ -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.
|
||||||
Loading…
Reference in a new issue