Add policy_metadata/README.md
This commit is contained in:
parent
71db392ce3
commit
cdbed168d1
1 changed files with 157 additions and 0 deletions
157
policy_metadata/README.md
Normal file
157
policy_metadata/README.md
Normal file
|
|
@ -0,0 +1,157 @@
|
||||||
|
# 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
|
||||||
Loading…
Reference in a new issue