From 31a1ad8debee00b35faf426ebd9fb973ea4fb4ab Mon Sep 17 00:00:00 2001
From: Mika <kontakt@donau2space.de>
Date: Thu, 15 Jan 2026 10:47:40 +0000
Subject: [PATCH] Add readme_md

---
 readme_md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 readme_md

diff --git a/readme_md b/readme_md
new file mode 100644
index 0000000..3197d68
--- /dev/null
+++ b/readme_md
@@ -0,0 +1,105 @@
+# publish_timeline_analysis
+
+## Überblick
+Dieses Repository dokumentiert und implementiert den Versuchsaufbau *publish_timeline_analysis*. Das Experiment untersucht die Analyse und Sichtbarmachung von Publish-Reihenfolgen in einem komplexen Systemumfeld mit Fokus auf eBPF-Instrumentation, Event-Korrelation und Merging-Strategien.
+
+**Link zum Artikel:** [https://donau2space.de/tag-119-1135-nebel-frisst-die-donau-und-ich-zeichne-endlich-eine-saubere-publish-timeline-fuer-case_03-04/](https://donau2space.de/tag-119-1135-nebel-frisst-die-donau-und-ich-zeichne-endlich-eine-saubere-publish-timeline-fuer-case_03-04/)  
+**Git Repository:** [https://git.donau2space.de/Mika/publish_timeline_analysis](https://git.donau2space.de/Mika/publish_timeline_analysis)
+
+### Hinweis
+Alle Inhalte wurden per KI generiert.  
+Nutzung, Anpassung und Weiterentwicklung erfolgen eigenverantwortlich auf eigenes Risiko.  
+Es wird keine Korrektheit, Sicherheit, Funktionsfähigkeit oder rechtliche Eignung zugesichert.
+
+## Inhalt des Repositories
+Das Repository umfasst drei Python-Skripte, die Analyse und Instrumentation von Publish-Events unterstützen.
+
+### Artefakte
+
+#### 1. ebpf_trace_instrumentation
+- **Art:** python_script  
+- **Ziel:** linux-demo  
+- **Sprachen:** Python  
+- **Zweck:** Erweiterung der eBPF-Instrumentation zur Erfassung von Publish-Events in Linux-Umgebungen.  
+
+**API-Funktionen:**  
+- `add_event(event_type, event_data)` – Fügt ein neues Event in den eBPF-Trace-Kontext ein.
+
+**Datenstruktur:**  
+- `PublishEvent` – JSON-Struktur mit Feldern: `ktime_ns`, `CPU`, `field_tag`, `new_value_hash`, `corr_id`.
+
+#### 2. trace_event_merging
+- **Art:** python_script  
+- **Ziel:** linux-demo  
+- **Sprachen:** Python  
+- **Zweck:** Merging von Read- und Write-Events zu konsistenten Publish-Sequenzen.  
+
+**API-Funktionen:**  
+- `merge_events(read_events, write_events)` – Kombiniert Ereignisse anhand von Korrelations-IDs zu einer Merge-Sequenz.
+
+**Datenstruktur:**  
+- `MergedEvent` – JSON-Struktur mit Feldern: `corr_id`, `combined_sequence`.
+
+#### 3. window_sweep_analysis
+- **Art:** python_script  
+- **Ziel:** linux-demo  
+- **Sprachen:** Python  
+- **Zweck:** Analyse von Zeitfenstern und ihrer Auswirkungen auf Publish-Sequenzen.  
+
+**API-Funktionen:**  
+- `perform_window_sweep(window_sizes)` – Führt eine Analyse mehrerer Betrachtungsfenster aus und liefert Abweichungsmetriken.
+
+**Datenstruktur:**  
+- `SweepResult` – JSON-Struktur mit Feldern: `window_size`, `mismatch_count`, `retry_burst_width`.
+
+## Installation & Nutzung
+
+### Voraussetzungen
+- Python 3.9 oder höher  
+- Linux-System mit eBPF-Unterstützung  
+- `bcc`- oder `bpftrace`-Tooling (optional für erweiterte Tracing-Analyse)
+
+### Installation
+1. Repository klonen:
+   
+   `git clone https://git.donau2space.de/Mika/publish_timeline_analysis`
+
+2. Abhängigkeiten installieren:
+   
+   `pip install -r requirements.txt`
+
+3. Skripte ausführbar machen (optional):
+   
+   `chmod +x *.py`
+
+### Nutzung
+
+Beispiel für die Nutzung der drei Module:
+1. Erfassung von Publish-Events:
+   
+   `python ebpf_trace_instrumentation.py`
+2. Merging der Events:
+   
+   `python trace_event_merging.py`
+3. Analyse nach Fenstergrößen:
+   
+   `python window_sweep_analysis.py`
+
+## Typische Use-Cases
+- Validierung von Publish-Ordern in Multicore-Systemen
+- Experimentelle Korrelation von Event-Timelines mittels eBPF
+- Zeitfensteranalyse für Publish-Resequencing-Mechanismen
+- Erstellung von Trace-basierten Visualisierungen
+
+## Struktur & Erweiterbarkeit
+Die drei Python-Module sind unabhängig strukturiert, arbeiten jedoch auf einem gemeinsamen Datenmodell (Publish-Events).  
+Erweiterungen können erfolgen durch:
+- zusätzliche Event-Typen in `ebpf_trace_instrumentation`
+- neue Merge-Strategien in `trace_event_merging`
+- zusätzliche Metriken in `window_sweep_analysis`
+
+Die JSON-basierten Datenstrukturen erleichtern die Integration in externe Analysepipelines.
+
+## Lizenz
+Veröffentlicht unter der **MIT-Lizenz**.  
+Nutzung und Weiterentwicklung erfolgen auf eigene Verantwortung.