Add logging_format/README.md

logging_format/README.md

@@ -0,0 +1,165 @@
+# Logging-Format für Run #13 (minimale Intervention mit Retry-Mechanismus)
+
+## Purpose
+
+Spezifikation des erweiterten Logging-Formats für die Messungen im Run #13 mit minimaler Intervention zur Behandlung von Δt<0-Fällen.
+
+**Problemstellung:** In Run #13 wurde ein inkonsistentes Auftreten von negativen Δt-Werten beobachtet. Es wurde ein Retry-Mechanismus eingeführt, der exakt einmal bei Δt<0 greift. Das Logging-Format musste erweitert werden, um Retry-Aktivität und Korrekturstatus erkennbar zu machen.
+
+**Ziele:**
+- Kompatibilität mit Logging-Formaten der Runs #11 und #12 sicherstellen
+- Integration zusätzlicher Felder zur Nachverfolgung des Retry-Mechanismus
+- Analysefähigkeit für Δt<0-Kandidaten erhalten
+
+## Kontext & Hintergrund
+
+Zeitmessungen pro Stratum (fresh/near-expiry) und Pinning-Status (pinned/unpinned).
+
+**Gruppierung:**
+- fresh-pinned
+- fresh-unpinned
+- near-expiry-pinned
+- near-expiry-unpinned
+
+**Trace-Metadaten / zusätzliche Tags:**
+- Messzeitpunkt
+- Δt-Berechnung
+- Retry-Zustand
+
+**Domänenkontext:**
+- Zeitmessstabilität bei near-expiry-Objekten
+- Einflussfaktoren auf Δt-Streuung
+- Laufzeitverhalten im Kurzfenster unter 200 ms
+
+**Outlier-Definition:**
+- Methode: Δt<0-Erkennung
+- Beschreibung: Eine Messung gilt als Ausreißer, wenn die beobachtete Zeitdifferenz Δt negativ ist.
+- Metrik: Δt
+
+**Motivation:**
+- Prüfen, ob minimaler Eingriff Fehlerfälle stabilisiert
+- Systemverhalten bei near-expiry-unpinned-Stratum isoliert analysieren
+- Kompatibilität der Messserien sicherstellen
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Ein Retry-Mechanismus wird bei Δt<0 ausgelöst.
+- Nach exakt einem Retry erfolgt erneute Messung.
+- Das zweite Ergebnis ersetzt das erste.
+- Keine Heuristiken oder mehrere Wiederholungen.
+
+**Algorithmen / Verfahren:**
+- Erfassen von Δt pro Messung.
+- Prüfen auf Δt<0.
+- Falls true: warten um festen Delay.
+- Einmalige Wiederholung der Messung.
+- Speichern des Retry-Zustands im Log.
+
+## Input / Output
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- timestamp
+- Δt
+- stratum
+- pinned
+- retry_taken
+- retry_fixed
+
+**Formatbeispiele:**
+- {"timestamp":"2024-04-12T08:43:10.158Z","Δt":-18.2,"stratum":"near-expiry-unpinned","pinned":false,"retry_taken":true,"retry_fixed":true}
+
+**Trace-Daten:**
+- Format: JSON-Zeilenformat
+- Hinweis: Die Felder retry_taken und retry_fixed sind nur im Stratum near-expiry-unpinned relevant.
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- warn_rate
+- unknown_rate
+- count(Δt<0_pre_retry)
+- count(Δt<0_post_retry)
+
+**Vergleichsausgaben:**
+- Run #12 vs Run #13
+  - Δ: Δt<0-Inzidenz vor Retry vs. nach Retry
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Filterung nach Stratum near-expiry-unpinned.
+- Erkennen von Δt<0-Fällen.
+- Überprüfen, ob retry_taken==true.
+- Auswertung der retry_fixed-Raten.
+- Vergleich mit Vorläufen #11 und #12 zur Stabilitätsbewertung.
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Kompatibilität der Logstruktur zwischen den Runs.
+
+**Erforderliche Tags & Metadaten:**
+- timestamp
+- Δt
+- retry_taken
+- retry_fixed
+
+**trace-cmd-Setup:**
+- Keine zusätzlichen Sensoren aktivieren.
+- Standardbuffergröße beibehalten.
+- Retry nur auf Δt<0 triggern.
+
+**Run-Design für Contributors:**
+- Run-Struktur nicht ändern.
+- Messbedingungen gleich zu #11/#12 halten.
+- Keine neuen Strata oder Schwellen einführen.
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Alle Δt<0-Kandidaten wurden durch einmaligen Retry korrigiert (retry_fixed=true).
+- Kein Anstieg der warn_rate oder unknown_rate im Vergleich zu Vorläufen.
+- Δt≥0 nach Retry in 100 % der beobachteten Fälle.
+
+**Implikationen für Experimente:**
+- Einmaliger Retry kann Δt-Stabilität im near-expiry-Bereich sicherstellen.
+- Weitere Messungen mit größerer Stichprobe erforderlich zur Quantifizierung der Latenzkosten.
+
+**Planungsziel:**
+- Ziel: Nachweis, dass minimaler Retry lokale Instabilität zuverlässig eliminiert.
+- Vorgehen:
+  - Target-Stratum begrenzen.
+  - Nur bei Δt<0 eingreifen.
+  - Base configuration unverändert lassen.
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Begrenzte Samplegröße reduziert Aussagekraft.
+- Retry-Dauer bisher nicht als Messgröße enthalten.
+
+**Kausalität & Generalisierbarkeit:**
+- Ergebnis nur für near-expiry-unpinned-Stratum valide.
+- Kein Nachweis für langfristige Stabilisierung oder andere Kontexte.
+
+**Praktische Fallstricke:**
+- Retry könnte in Lastsituationen Timingverhalten verzerren.
+- Fehlende Quantifizierung der Retry-Latenz.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- Erweiterung der Stichprobe auf mehrere Tagesläufe.
+- Direkte Messung der Retry-Latenzzeit.
+
+**Analyseziele:**
+- Quantitative Bewertung der Stabilisierung vs. Latenzkosten.
+- Überprüfung der Robustheit gegen Zufallsfluktuationen.
+
+**Regression & Modellierung:**
+- Fit eines einfachen Modells zur Wahrscheinlichkeit Δt<0 vor und nach Retry.
+
+**Community-Beiträge:**
+- Bereitstellung der Logformate zur externen Validierung und Reanalyse.