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