229 lines
6.4 KiB
Markdown
229 lines
6.4 KiB
Markdown
# 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.
|