Add rollout_series_report/README.md
This commit is contained in:
parent
86c1b0fafa
commit
b24ce1cddc
1 changed files with 187 additions and 0 deletions
187
rollout_series_report/README.md
Normal file
187
rollout_series_report/README.md
Normal file
|
|
@ -0,0 +1,187 @@
|
|||
# Rollout-Serie und Stabilitätsanalyse für Gate‑V1
|
||||
|
||||
## Purpose
|
||||
|
||||
Erstellung einer reproduzierbaren Rollout-Analyse aus CI-Artefakten zur Stabilisierung und Vorbereitung des Gate‑V1‑Systems auf produktive Nutzung.
|
||||
|
||||
**Problemstellung:** Gate‑V1 generiert CI‑Feedback, aber ohne belastbare Zeitreihen oder Kontrollwerte. Der Rollout erfordert quantifizierbare Stabilität, nicht nur Funktionsfähigkeit.
|
||||
|
||||
**Ziele:**
|
||||
- Aggregierte Metriken über CI‑Runs erfassen
|
||||
- Unknown‑Raten analysieren und klassifizieren
|
||||
- Deterministische CSV‑Basis für Rollout‑Entscheidungen erzeugen
|
||||
- Whitelist‑Mechanismus für Unknown‑Klassen implementieren
|
||||
|
||||
## Kontext & Hintergrund
|
||||
|
||||
Sammlung von CI‑Artefakten im JSON‑Format (gate_result.json) pro Run.
|
||||
|
||||
**Gruppierung:**
|
||||
- policy_hash
|
||||
- outcome
|
||||
- unknown_rate
|
||||
- top_reasons
|
||||
|
||||
**Trace-Metadaten / zusätzliche Tags:**
|
||||
- policy_hash zur Versionsidentifikation
|
||||
- unknown_rate als Qualitätskennzahl pro Run
|
||||
|
||||
**Domänenkontext:**
|
||||
- CI/CD‑Systemintegration
|
||||
- Gating‑Mechanismen für Software‑Deployments
|
||||
|
||||
**Outlier-Definition:**
|
||||
- Methode: Identifikation wiederkehrender Unknown‑Klassen
|
||||
- Beschreibung: Spitzenwerte (Spikes) in Unknown‑Raten werden nach Top‑Reason gruppiert und korreliert mit Fail‑Signalen überprüft.
|
||||
- Metrik: unknown_rate
|
||||
|
||||
**Motivation:**
|
||||
- Übergang von subjektivem CI‑Monitoring zu messbarer Rollout‑Kontrolle
|
||||
- Reduktion von False‑Positives durch Unknown‑Klassifikation
|
||||
- Erhöhung der Policy‑Stabilität durch deterministische Aggregation
|
||||
|
||||
## Methode / Spezifikation
|
||||
|
||||
**Übersicht:**
|
||||
- Script rollup_rollout.py verarbeitet gate_result.json‑Dateien zu rollout_series.csv.
|
||||
- Jeder Datensatz repräsentiert einen CI‑Run mit Policy‑Version und Ergebnissen.
|
||||
- Unknown‑Klassen werden durch zusätzlichen Whitelist‑Mechanismus getrennt beobachtet.
|
||||
|
||||
**Algorithmen / Verfahren:**
|
||||
- Einlesen aller gate_result.json aus definiertem Artefakt‑Verzeichnis
|
||||
- Extraktion der Felder policy_hash, outcome, unknown_rate, top_reasons
|
||||
- Deterministisches Aggregieren zu rollout_series.csv
|
||||
- Optionales Mapping von Unknowns gegen unknown_whitelist.json
|
||||
|
||||
### Bootstrap-Übersicht
|
||||
|
||||
Kein numerisches Resampling; Serie dient als deterministische Beobachtung über Läufe.
|
||||
|
||||
**Zielgrößen:**
|
||||
- unknown_rate_min
|
||||
- unknown_rate_median
|
||||
- unknown_rate_max
|
||||
- Häufigkeiten von Unknown‑Klassen
|
||||
|
||||
### Abgeleitete Effektgrößen
|
||||
|
||||
**Risk Difference (Differenz der Raten):**
|
||||
- Definition: Vergleich der Unknown‑Raten zwischen Whitelist‑ und Non‑Whitelist‑Klassen.
|
||||
- Bootstrap: Keine Bootstrap‑Anwendung; feste Häufigkeitszählung.
|
||||
|
||||
**Risk Ratio:**
|
||||
- Definition: Optionaler Indikator bei Übergang zu WARN‑Phase zur Beobachtung von Signal‑vs‑Unknown‑Verhalten.
|
||||
- Bootstrap: Nicht implementiert.
|
||||
|
||||
## Input / Output
|
||||
|
||||
### Input-Anforderungen
|
||||
|
||||
**Hardware:**
|
||||
**Software:**
|
||||
- Python ≥ 3.9
|
||||
- JSON‑fähiges Dateisystem
|
||||
- Zugriff auf CI‑Artefakte
|
||||
|
||||
**Konfiguration:**
|
||||
- Path zur Sammlung der gate_result.json‑Dateien
|
||||
- optional: unknown_whitelist.json im Root‑Verzeichnis
|
||||
|
||||
### Erwartete Rohdaten
|
||||
|
||||
**Felder pro Run:**
|
||||
- policy_hash
|
||||
- outcome
|
||||
- unknown_rate
|
||||
- top_reasons
|
||||
|
||||
**Formatbeispiele:**
|
||||
- { "policy_hash": "a6f53e", "outcome": "COMMENT", "unknown_rate": 0.08, "top_reasons": ["flaky_test"] }
|
||||
|
||||
**Trace-Daten:**
|
||||
- Format: CSV-Ausgabe rollout_series.csv
|
||||
- Hinweis: Alle Einträge deterministisch sortiert nach Run‑ID oder Timestamp
|
||||
|
||||
### Analyse-Ausgaben
|
||||
|
||||
**Pro Gruppe / pro Governor:**
|
||||
- unknown_rate_min
|
||||
- unknown_rate_median
|
||||
- unknown_rate_max
|
||||
- class_frequency_table
|
||||
|
||||
**Vergleichsausgaben:**
|
||||
|
||||
- Trace-Muster: Identifikation wiederkehrender Unknown‑Muster je policy_hash
|
||||
|
||||
## Workflow / Nutzung
|
||||
|
||||
**Analyse-Workflow:**
|
||||
- CI‑Runs durchführen und gate_result.json erzeugen
|
||||
- Script rollup_rollout.py ausführen
|
||||
- Output in rollout_series.csv prüfen
|
||||
- Optional: unknown_whitelist.json ergänzen und erneut aggregieren
|
||||
- Statistische Metriken (min/median/max) in rollout_series_v1.md dokumentieren
|
||||
|
||||
### Trace-Template-Anforderungen
|
||||
|
||||
**Ziel:** Einheitliche Sammlung von Gate‑Ergebnissen über viele Runs zur Aufdeckung systematischer Muster.
|
||||
|
||||
**Erforderliche Tags & Metadaten:**
|
||||
- policy_hash
|
||||
- unknown_rate
|
||||
- top_reasons
|
||||
|
||||
**trace-cmd-Setup:**
|
||||
- CI muss Artefakte mit gate_result.json generieren
|
||||
- rollup_rollout.py benötigt Pfadvariable CI_ARTIFACT_PATH
|
||||
|
||||
**Run-Design für Contributors:**
|
||||
- Mindestens 40 Runs zur Ableitung stabiler Schwellenwerte sammeln
|
||||
|
||||
## Interpretation & erwartete Ergebnisse
|
||||
|
||||
**Kernbefunde:**
|
||||
- Unknown‑Spitzen korrelieren überwiegend mit wiederkehrenden spezifischen Top‑Reasons.
|
||||
- Echte FAIL‑Signale treten unabhängig von diesen Unknown‑Mustern auf.
|
||||
- Unknown‑Klasse kann strukturiert reduziert werden.
|
||||
|
||||
**Implikationen für Experimente:**
|
||||
- Whitelist‑Definition dient als Instrument zur kontrollierten Reduktion von Pseudo‑Anomalien.
|
||||
- Gate‑Kommentare werden kompakter und klarer, was Akzeptanz im CI‑Prozess erhöht.
|
||||
|
||||
**Planungsziel:**
|
||||
- Ziel: Beginn der WARN‑Phase mit definierten Schwellen für Unknown‑Rate und Outcome‑Mapping.
|
||||
- Vorgehen:
|
||||
- Rollout‑Serie bis N≈40 erweitern
|
||||
- Median‑basierten Threshold bestimmen
|
||||
- False‑Positive‑Rate vor Phase‑Wechsel bewerten
|
||||
|
||||
## Limitationen & Fallstricke
|
||||
|
||||
**Datenbezogene Limitationen:**
|
||||
- Ungleichmäßige Run‑Verteilung kann Median verzerren
|
||||
- Fehlende oder fehlerhafte JSON‑Felder führen zu unvollständiger CSV
|
||||
|
||||
**Kausalität & Generalisierbarkeit:**
|
||||
- Korrelation zwischen Unknown‑Rate und Fail‑Signalen ist nicht notwendigerweise kausal
|
||||
|
||||
**Praktische Fallstricke:**
|
||||
- Whitelist‑Pflege erfordert Disziplin und regelmäßige Revision
|
||||
- Fehlende Konsistenz in policy_hash‑Versionierung erschwert Langzeitvergleiche
|
||||
|
||||
## Nächste Schritte & Erweiterungen
|
||||
|
||||
**Geplante Experimente:**
|
||||
- Rollout‑Serie mit ≥40 Runs erweitern
|
||||
- Threshold‑Tuning für WARN‑Schwelle testen
|
||||
|
||||
**Analyseziele:**
|
||||
- Quantitative Bestimmung der False‑Positive‑Reduktion
|
||||
- Messung der Unknown‑Ratenstabilität über Policy‑Versionen hinweg
|
||||
|
||||
**Regression & Modellierung:**
|
||||
- Optionale Risikomodellierung Unknown_vs_Fail‑Ratio
|
||||
|
||||
**Community-Beiträge:**
|
||||
- Struktur und CSV‑Format für andere Gate‑Rollouts freigeben
|
||||
Loading…
Reference in a new issue