157 lines
4.5 KiB
Markdown
157 lines
4.5 KiB
Markdown
# Policy Monitoring und Metrik-Dokumentation
|
||
|
||
## Purpose
|
||
|
||
Dokumentation der Metriken, Schwellenwerte und Metadaten zur Überwachung eines Policy-Rollouts.
|
||
|
||
**Problemstellung:** Zur Laufzeitüberwachung von Policy-Rollouts müssen Zustände, Fehler und Unbekannte robust gezählt und dokumentiert werden, um fundierte Aktivierungsentscheidungen zu treffen.
|
||
|
||
**Ziele:**
|
||
- Definieren von Go/No-Go-Schwellenwerten für Policy-Aktivierung
|
||
- Absicherung der Fehlertoleranz in der Metrikerfassung
|
||
- Sicherstellung reproduzierbarer CI-Ausgaben über Versions-Hashes
|
||
|
||
## Kontext & Hintergrund
|
||
|
||
Aggregierte Auswertung von drift_report.json und rollout_metrics.json während des Policy‑Tests.
|
||
|
||
**Gruppierung:**
|
||
- pinned
|
||
- unpinned
|
||
- unknowns
|
||
|
||
**Trace-Metadaten / zusätzliche Tags:**
|
||
- policy_hash
|
||
- policy_constants.json
|
||
- drift_report.json
|
||
- rollout_metrics.json
|
||
|
||
**Domänenkontext:**
|
||
- Policy-Rollout-Überwachung
|
||
- CI-Auswertung
|
||
- Fehlerklassifikation
|
||
|
||
**Motivation:**
|
||
- Reduktion zufälliger Policy‑Fehler durch frühe Metrikprüfung
|
||
- Verbesserte Vergleichbarkeit und Nachvollziehbarkeit zwischen Policy‑Versionen
|
||
|
||
## Methode / Spezifikation
|
||
|
||
**Übersicht:**
|
||
- Verwendung von Go/No-Go‑Regeln für die Policy‑Aktivierung nach 30 Runs oder 7 Tagen
|
||
- Aggregieren der Metriken WARN, FAIL, Unknowns und Overrides pro Stratum
|
||
- Einbindung eines policy_hash zur Versions‑Nachvollziehbarkeit
|
||
|
||
**Algorithmen / Verfahren:**
|
||
- Zählen von WARN und FAIL pro Stratum aus den Drift‑Reports
|
||
- Ermittlung der Unknown‑Rate und Ursache (Contract/Schema)
|
||
- Erfassen von Overrides pro Run mit Flag oder Defaultwert
|
||
- Einordnung fehlender Felder als Unknown‑Klasse unknown_field_missing
|
||
- Sortierung der Ausgabe alphabetisch nach Keys und namenbasiert in Arrays
|
||
|
||
## Input / Output
|
||
|
||
### Input-Anforderungen
|
||
|
||
**Hardware:**
|
||
**Software:**
|
||
- Python (policy_eval.py)
|
||
- CI‑System mit Zugriff auf drift_report.json
|
||
|
||
**Konfiguration:**
|
||
- Schema‑Definition für Drift‑Reports
|
||
- Konfigurierbare Policy‑Schwellenwerte
|
||
|
||
### Erwartete Rohdaten
|
||
|
||
**Felder pro Run:**
|
||
- run_id
|
||
- policy_state
|
||
- WARN_count
|
||
- FAIL_count
|
||
- Unknown_count
|
||
- Overrides_count
|
||
|
||
**Formatbeispiele:**
|
||
- {"run_id": "r001", "policy_state": "pinned", "WARN_count": 1, ... }
|
||
|
||
**Trace-Daten:**
|
||
- Format: JSON
|
||
- Hinweis: Fehlende Felder werden automatisch als Unknown‑Klasse klassifiziert.
|
||
|
||
### Analyse-Ausgaben
|
||
|
||
**Pro Gruppe / pro Governor:**
|
||
- WARN/FAIL‑Rate pro Stratum
|
||
- Unknown‑Klassifikation nach Ursache
|
||
- Overrides pro Run
|
||
|
||
**Vergleichsausgaben:**
|
||
- pinned vs unpinned
|
||
- Δ: Differenz der kombinierten WARN+FAIL‑Rate
|
||
|
||
- Trace-Muster: Stabilitätsprüfung über 30 Runs oder 7 Tage bezogen auf policy_hash
|
||
|
||
## Workflow / Nutzung
|
||
|
||
**Analyse-Workflow:**
|
||
- Laden der letzten Drift‑Reports
|
||
- Erzeugen der rollout_metrics.json mit Aggregaten
|
||
- Härten der policy_eval.py gegen Feldfehler
|
||
- Sortierte JSON‑Ausgabe für CI‑Diff
|
||
- Einfügen des policy_hash in CI‑Kommentar
|
||
|
||
### Trace-Template-Anforderungen
|
||
|
||
**Ziel:** Sicherstellen, dass alle Drift‑Report‑Datensätze vollständig oder ersetzbar sind
|
||
|
||
**Erforderliche Tags & Metadaten:**
|
||
- policy_hash
|
||
- schema_version
|
||
- policy_state
|
||
|
||
**trace-cmd-Setup:**
|
||
- Log‑Extraktion über CI‑Pipeline nach jedem Run
|
||
|
||
**Run-Design für Contributors:**
|
||
- Mindestens 30 Runs, gemischte Policy‑Strata (pinned/unpinned)
|
||
|
||
## Interpretation & erwartete Ergebnisse
|
||
|
||
**Kernbefunde:**
|
||
- System verhält sich stabil trotz unvollständiger Felder.
|
||
- Diff‑freundliche Ausgaben reduzieren CI‑Rauschen signifikant.
|
||
- Go/No‑Go‑Regel operationalisiert Policy‑Freigaben mit klaren numerischen Grenzen.
|
||
|
||
**Implikationen für Experimente:**
|
||
- Frühzeitige Aktivierung des WARN‑Gates möglich, wenn Schwellen vor Tag 7 erfüllt sind.
|
||
|
||
**Planungsziel:**
|
||
- Ziel: Stabile Policy‑Überwachung ohne Betriebsabbrüche
|
||
- Vorgehen:
|
||
- Schwellenwerte definieren
|
||
- Metriken automatisiert zählen
|
||
- Fehler tolerant klassifizieren
|
||
|
||
## Limitationen & Fallstricke
|
||
|
||
**Datenbezogene Limitationen:**
|
||
- Fehlende Felder können semantische Lücken verdecken, wenn Unknown‑Klassifikation zu grob bleibt.
|
||
|
||
**Kausalität & Generalisierbarkeit:**
|
||
- Metrikschwellen basieren nur auf beobachteten Runs und sind nicht kausal verallgemeinerbar.
|
||
|
||
**Praktische Fallstricke:**
|
||
- Manuelle Overrides können unbemerkt den Go/No‑Go‑Status verzerren.
|
||
|
||
## Nächste Schritte & Erweiterungen
|
||
|
||
**Geplante Experimente:**
|
||
- Schema‑Check mit Defaultwerten vor Policy‑Evaluation
|
||
|
||
**Analyseziele:**
|
||
- Vereinheitlichung der Unknown‑Labels
|
||
- Automatische Erkennung fehlerhafter Reports
|
||
|
||
**Community-Beiträge:**
|
||
- Definition eines offenen Schemas für rollout_metrics.json
|