| .. | ||
| README.md | ||
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