policy_metrics_monitoring/policy_metadata/README.md

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