Add affinity_analysis_documentation/README.md

affinity_analysis_documentation/README.md

@@ -0,0 +1,165 @@
+# Interaktionsanalyse Affinität × Last: Bandbreite und Retry-Tail
+
+## Purpose
+
+Quantitative Analyse der Wechselwirkung zwischen CPU-Affinität und Lastniveau anhand gemessener Effekte auf Bandbreite und Retry-Tail-Verhalten.
+
+**Problemstellung:** Bestimmung, ob sich der Affinitätseffekt auf Durchsatz und Tail-Verhalten bei höherer Last additiv oder multiplikativ (interaktiv) verstärkt.
+
+**Ziele:**
+- Numerische Bestimmung des Interaktionseffekts zwischen Affinität und Last auf Bandbreite.
+- Identifikation nichtlinearer Effekte bei zunehmender Parallelität.
+- Festlegung quantitativer Schwellen zur Definition überproportionaler Reaktionen.
+
+## Kontext & Hintergrund
+
+Vier Messläufe mit Kombinationen aus Affinitätseinstellung (randomized/enforced) und Laststufen (2×, 4×).
+
+**Gruppierung:**
+- Affinitätsregime
+- Lastfaktor
+
+**Trace-Metadaten / zusätzliche Tags:**
+- setup_fingerprint
+- policy_hash
+- burst_window
+
+**Domänenkontext:**
+- CPU-Affinität
+- Parallelisierung
+- Systemdurchsatzanalyse
+
+**Outlier-Definition:**
+- Methode: Tailanalyse (p99 Retry-Rate)
+- Beschreibung: Varianz und Latenzspitzen bei hoher Last gelten als Ausreißerindikatoren.
+- Metrik: retry_tail_p99
+
+**Motivation:**
+- Vermeidung subjektiver Interpretation durch Definition harter numerischer Schwellen.
+- Verständnis der Kopplung zwischen Scheduling, Queueing und Misch-Effekten unter intensiver Last.
+
+## Methode / Spezifikation
+
+**Übersicht:**
+- Vergleichende Auswertung von Bandbreiten- und Retry-P99-Messungen in vier definierten Runs.
+- Berechnung der Differenzen (Effekte) innerhalb und zwischen Laststufen.
+- Anwendung des Diff-of-Diffs-Prinzips zur Isolierung der Interaktion.
+
+**Algorithmen / Verfahren:**
+- Berechne pro Laststufe den Affinitätseffekt: enforced − randomized.
+- Berechne die Interaktion als Differenz dieser Effekte zwischen Laststufen.
+- Bewerte zusätzliche Verschärfung der Bandbreitenverengung oder Retry-Tail-Erhöhung als nichtlinear.
+
+### Abgeleitete Effektgrößen
+
+**Risk Difference (Differenz der Raten):**
+- Definition: Differenz der Effektgrößen bei zwei Lastniveaus (Diff-of-Diffs).
+- Bootstrap: Optionaler Einsatz zur Abschätzung der Stabilität der Differenzen über mehrere Runs.
+
+**Risk Ratio:**
+- Definition: Verhältnis des Retry-p99 zwischen Affinitätsregimen pro Lastniveau.
+- Bootstrap: Geeignet, um Varianz im Tailverhalten zu quantifizieren.
+
+## Input / Output
+
+### Erwartete Rohdaten
+
+**Felder pro Run:**
+- run_id
+- affinity_mode
+- load_factor
+- band_width_h
+- retry_tail_p99
+- setup_fingerprint
+
+**Formatbeispiele:**
+- 29, randomized, 2x, 6.8, 0.11, hash1234
+
+**Trace-Daten:**
+- Format: CSV oder JSON aus Zeitserienexport
+- Hinweis: Zeiterprobte Aggregation auf Stundenbasis (band_width) und Perzentilberechnung (p99 Retry).
+
+### Analyse-Ausgaben
+
+**Pro Gruppe / pro Governor:**
+- Mittelwert Bandbreite
+- p99 Retry-Rate
+- Affinitätseffekt je Last
+
+**Vergleichsausgaben:**
+- Affinitäts-Effekt @4× vs Affinitäts-Effekt @2×
+  - Δ: −1.4 h Bandbreite
+  - RR: +11 % Retry-p99 (unter enforced bei 4×)
+
+## Workflow / Nutzung
+
+**Analyse-Workflow:**
+- Sammle Messdaten für 2× und 4× Last jeweils mit enforced/randomized Affinität.
+- Berechne pro Laststufe enforced − randomized.
+- Berechne Interaktion als Differenz der beiden Effekte.
+- Definiere Nichtlinearitätskriterien für 8×-Runs.
+
+### Trace-Template-Anforderungen
+
+**Ziel:** Nachvollziehbare Quantifizierung der Affinität×Last-Interaktion.
+
+**Erforderliche Tags & Metadaten:**
+- load_factor
+- affinity_mode
+- band_width
+- retry_tail_p99
+- setup_fingerprint
+
+**trace-cmd-Setup:**
+- Einheitliches Sampling-Intervall
+- identisches Policy-Setup zwischen Runs
+
+**Run-Design für Contributors:**
+- Zwei Lastfaktoren (2×, 4×)
+- Beide Affinitätsmodi pro Lastfaktor
+- Konsistente Umgebungsbedingungen
+
+## Interpretation & erwartete Ergebnisse
+
+**Kernbefunde:**
+- Affinitäts-Effekt verstärkt sich nichtlinear bei höherer Last.
+- Bandbreitenverengung bei 4× Last deutlich größer als bei 2×.
+- Retry-Tail erhöht sich nur unter starker Last signifikant.
+
+**Implikationen für Experimente:**
+- Erweiterung auf 8× dient zur Validierung der Nichtlinearität.
+- Ermöglicht Definition operationaler Lastgrenzen vor systemischer Sättigung.
+
+**Planungsziel:**
+- Ziel: Bestimmung des Sättigungspunkts zwischen Queuing- und Mixing-Dominanz.
+- Vorgehen:
+  - Messung des Bandbreitenverlusts und Retry-Tail-Verhaltens bei 8× unter konstanter Affinität.
+
+## Limitationen & Fallstricke
+
+**Datenbezogene Limitationen:**
+- Kleine Stichprobe (nur vier Runs).
+- Mögliche Messunsicherheiten durch Umgebungsvariabilität.
+
+**Bootstrap-spezifische Limitationen:**
+- Nicht angewendet, daher keine Varianzabschätzung der Effektgrößen.
+
+**Kausalität & Generalisierbarkeit:**
+- Interaktion numerisch beschrieben, aber noch nicht kausal erklärt.
+
+**Praktische Fallstricke:**
+- Verwechslung additiver und interaktiver Effekte bei unsauberer Vorzeichenkonvention.
+
+## Nächste Schritte & Erweiterungen
+
+**Geplante Experimente:**
+- 8× Run mit konstanter Affinität und stabiler Policy.
+
+**Analyseziele:**
+- Validierung der Nichtlinearität und Bestimmung des Sättigungspunktes.
+
+**Regression & Modellierung:**
+- Mehrfaktorielle Varianzanalyse (ANOVA) zur formalen Testung der Interaktion.
+
+**Community-Beiträge:**
+- Bereitstellung der Trace-Templates und Effekttabellen für Vergleichsanalysen.