# 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.