Add drift_report_md/README.md
This commit is contained in:
commit
82707c409a
1 changed files with 171 additions and 0 deletions
171
drift_report_md/README.md
Normal file
171
drift_report_md/README.md
Normal file
|
|
@ -0,0 +1,171 @@
|
|||
# Drift-Report Markdown Artefakt für CI-Bewertung
|
||||
|
||||
## Purpose
|
||||
|
||||
Erzeugt menschenlesbare Drift-Berichte aus CI-Läufen mit Betriebsmetriken und Warnindikatoren.
|
||||
|
||||
**Problemstellung:** Entwickler benötigen verständliche Drift-Indikatoren in CI-Reports, ohne manuelles Parsing von JSON-Daten.
|
||||
|
||||
**Ziele:**
|
||||
- Klarer Überblick über aktuelle Driftlage pro Pipeline-Fenster
|
||||
- Transparente Darstellung von PASS, WARN, FAIL Status
|
||||
- Erkennung von Anomalien durch pinned Warnungen
|
||||
|
||||
## Kontext & Hintergrund
|
||||
|
||||
CI-Laufdaten mit PASS/WARN/FAIL Labels über ein gleitendes Fenster.
|
||||
|
||||
**Gruppierung:**
|
||||
- Pipeline-Runs
|
||||
- zeitliches Rolling-Fenster
|
||||
|
||||
**Trace-Metadaten / zusätzliche Tags:**
|
||||
- run_id
|
||||
- job_status
|
||||
- debug_json_presence
|
||||
|
||||
**Domänenkontext:**
|
||||
- CI Monitoring
|
||||
- Drift Detection
|
||||
- Operational Reporting
|
||||
|
||||
**Outlier-Definition:**
|
||||
- Methode: Threshold-basiert
|
||||
- Beschreibung: WARN-Quote > 30 % im aktuellen Fenster signalisiert Drift.
|
||||
- Metrik: warn_ratio
|
||||
|
||||
**Motivation:**
|
||||
- Fehlerquellen in Model- oder Datenqualität früh erkennen
|
||||
- Fehlende Debug-JSONs sichtbar markieren statt still ignorieren
|
||||
- pinned Runs als Referenz stabil halten
|
||||
|
||||
## Methode / Spezifikation
|
||||
|
||||
**Übersicht:**
|
||||
- Report aggregiert Ergebnisse über ein konfiguriertes Fenster.
|
||||
- Parameter bestimmen Zählwerte und Schwellenbedingungen.
|
||||
- Markdown-Ausgabe betont kritische Kennzahlen fett.
|
||||
|
||||
**Algorithmen / Verfahren:**
|
||||
- Berechne gleitendes Fenster von window_size Läufen.
|
||||
- Zähle PASS, WARN, FAIL Ereignisse.
|
||||
- Berechne warn_ratio = warn_count / window_size.
|
||||
- Markiere pinned_warn_fail_count separat.
|
||||
- Exportiere strukturierte Markdown-Datei drift_report.md.
|
||||
|
||||
### Bootstrap-Übersicht
|
||||
|
||||
**Zielgrößen:**
|
||||
### Resampling-Setup
|
||||
|
||||
**Resampling-Schema:**
|
||||
**Konfidenzintervalle:**
|
||||
- Niveau: 0.95
|
||||
|
||||
### Abgeleitete Effektgrößen
|
||||
|
||||
### C-State-Kontrolle
|
||||
|
||||
**Vorgehen:**
|
||||
## Input / Output
|
||||
|
||||
### Input-Anforderungen
|
||||
|
||||
**Hardware:**
|
||||
**Software:**
|
||||
- CI Runner mit Zugriff auf Artefakt-Speicher
|
||||
- Python oder Shell-basierte Laufumgebung
|
||||
|
||||
**Konfiguration:**
|
||||
- window_size konfigurierbar
|
||||
- warn_ratio_threshold = 0.3
|
||||
- rerun_budget=1 optional
|
||||
|
||||
### Erwartete Rohdaten
|
||||
|
||||
**Felder pro Run:**
|
||||
- run_id
|
||||
- label
|
||||
- debug_json_available
|
||||
|
||||
**Formatbeispiele:**
|
||||
- { 'run_id': 184, 'label': 'WARN', 'debug_json_available': false }
|
||||
|
||||
**Trace-Daten:**
|
||||
- Format: JSON
|
||||
- Hinweis: drift_report.json dient als Eingabe für Markdown-Erzeugung
|
||||
|
||||
### Analyse-Ausgaben
|
||||
|
||||
**Pro Gruppe / pro Governor:**
|
||||
**Vergleichsausgaben:**
|
||||
|
||||
|
||||
## Workflow / Nutzung
|
||||
|
||||
**Analyse-Workflow:**
|
||||
- Job im CI ausführen.
|
||||
- Daten aus den letzten window_size Läufen aggregieren.
|
||||
- generate_drift_report_md(window_size, pass_count, warn_count, fail_count, warn_ratio, pinned_warn_fail_count) aufrufen.
|
||||
- Artefakt drift_report.md und drift_report.json publizieren.
|
||||
|
||||
### Trace-Template-Anforderungen
|
||||
|
||||
**Ziel:** Konsistentes Reporting über CI-Läufe hinweg.
|
||||
|
||||
**Erforderliche Tags & Metadaten:**
|
||||
- run_id
|
||||
- pipeline_id
|
||||
- status_label
|
||||
- pinned_flag
|
||||
|
||||
**trace-cmd-Setup:**
|
||||
- Sicherstellen, dass Job jedes Ergebnis im Artefaktpfad exportiert.
|
||||
|
||||
**Run-Design für Contributors:**
|
||||
- Neue Experimente sollen window_size und Schwellen konfigurieren und Ergebnisse vergleichen.
|
||||
|
||||
## Interpretation & erwartete Ergebnisse
|
||||
|
||||
**Kernbefunde:**
|
||||
- WARN-Rate stabil unter Schwelle signalisiert Systemgesundheit.
|
||||
- pinned_warn_fail_count > 0 indiziert potenzielle Regression oder Labeling-Problem.
|
||||
- Fehlende Debug-Dateien erzeugen expliziten unknown-Eintrag.
|
||||
|
||||
**Implikationen für Experimente:**
|
||||
- Rolling-Fenster-Anpassungen beeinflussen Sensitivität.
|
||||
- Drift-Warnschwelle kann CI-Stabilität vs. Reaktivität steuern.
|
||||
|
||||
**Planungsziel:**
|
||||
- Ziel: Live-Monitoring der Drift-Stabilität in CI-Umgebung.
|
||||
- Vorgehen:
|
||||
- Messung über feste Fenstergrößen
|
||||
- Erfassen von pinned States zur Drift-Bewertung
|
||||
|
||||
## Limitationen & Fallstricke
|
||||
|
||||
**Datenbezogene Limitationen:**
|
||||
- Fehlende Debug-JSONs können Statistik verzerren.
|
||||
- Geringe Fenstergröße reduziert Aussagekraft.
|
||||
|
||||
**Kausalität & Generalisierbarkeit:**
|
||||
- CI-spezifische Ergebnisse nicht direkt auf Produktionssysteme übertragbar.
|
||||
|
||||
**Praktische Fallstricke:**
|
||||
- Zu häufige WARNs können Alarmmüdigkeit verursachen.
|
||||
- Nicht-persistent gespeicherte Artefakte erschweren Nachvollziehbarkeit.
|
||||
|
||||
## Nächste Schritte & Erweiterungen
|
||||
|
||||
**Geplante Experimente:**
|
||||
- Vergleich von N=10 vs. N=20 Fenstern auf identischem Datensatz.
|
||||
- Einführung von Auto-Rerun (rerun_budget=1) zur Evaluierung.
|
||||
|
||||
**Analyseziele:**
|
||||
- Langzeitstabilität der Drift-Warnung untersuchen.
|
||||
|
||||
**Regression & Modellierung:**
|
||||
- Zusammenhang zwischen pinned Warnungen und Datenquellendrift analysieren.
|
||||
|
||||
**Community-Beiträge:**
|
||||
- Feedback zu Report-Darstellung (Markdown-Layout, Tabellenstruktur) einholen.
|
||||
Loading…
Reference in a new issue