Add README.md

README.md

@@ -0,0 +1,80 @@
+# publish_timing_analysis
+
+## Überblick
+
+Dieses Repository dokumentiert das Experiment **publish_timing_analysis**, das die Analyse von Publish-Timelines untersucht. Der Fokus liegt auf der Instrumentation von Write-Events und der Untersuchung der Auswirkungen von zeitlichen Faktoren auf die Systemleistung.
+
+**Artikel:** [https://donau2space.de/tag-120-1211-nebel-ueber-der-donau-und-ich-mache-die-publish-timeline-endlich-vollstaendig/](https://donau2space.de/tag-120-1211-nebel-ueber-der-donau-und-ich-mache-die-publish-timeline-endlich-vollstaendig/)
+
+**Git Repository:** [https://git.donau2space.de/Mika/publish_timing_analysis](https://git.donau2space.de/Mika/publish_timing_analysis)
+
+### Hinweis
+Alle Inhalte wurden per KI generiert.
+Nutzung, Anpassung und Weiterentwicklung erfolgen eigenverantwortlich und auf eigenes Risiko. Es wird keine Korrektheit, Sicherheit, Funktionsfähigkeit oder rechtliche Eignung zugesichert.
+
+## Inhalt des Repositories
+
+### Artefakt 1: 1_write_events
+- **Art:** Python-Skript (`python_script`)
+- **Ziel:** Linux Userspace
+- **Sprache:** Python
+- **Zweck:** Erfassung und Protokollierung von Write-Events der Variablen *base_raw* und *nsec_base*.
+
+**API-Funktion:**
+- `record_write_event(field_tag, new_value_hash, corr_id)` – zeichnet ein einzelnes Write-Event für ein spezifisches Feld auf.
+
+---
+
+### Artefakt 2: 2_trace_agg
+- **Art:** Python-Skript (`python_script`)
+- **Ziel:** Linux Userspace
+- **Sprache:** Python
+- **Zweck:** Aggregation und Analyse von Trace-Daten. Erzeugt strukturierte Schrittfolgen pro *corr_id*.
+
+**API-Funktion:**
+- `aggregate_trace_data(trace_data)` – aggregiert Trace-Einträge zu einem konsistenten, korrelationsbasierten Ablaufmodell.
+
+**Datenstruktur:**
+- `TraceEvent`: enthält `corr_id`, `step_sequence`, `timestamp`.
+
+---
+
+### Artefakt 3: 3_experiment_design
+- **Art:** Dokumentation (`doc_only`)
+- **Ziel:** Mixed
+- **Zweck:** Beschreibung des A/B-Designs zur Untersuchung der Unterschiede zwischen pinned und unpinned Publish-Bedingungen.
+
+## Installation & Nutzung
+
+### Voraussetzungen
+- Python ≥ 3.8
+- Zugriff auf eine Linux-Umgebung mit Schreibrechten im Userspace
+
+### Installation
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+### Nutzung
+Führe die Skripte in folgender Reihenfolge aus:
+1. `python 1_write_events.py` – Startet das Logging der Write-Events.
+2. `python 2_trace_agg.py` – Führt die Aggregationsanalyse über die gesammelten Trace-Daten aus.
+
+## Typische Use-Cases
+- Überwachung und Analyse von Publish-Event-Timelines.
+- Vergleich von Systemlatenzen bei unterschiedlichen Publish-Strategien.
+- Ermittlung systematischer Verzögerungen in Messketten.
+
+## Struktur & Erweiterbarkeit
+Das Repository ist modular aufgebaut:
+- **Erfassungsmodul**: Verarbeitung von Write-Events.
+- **Analysemodul**: Zusammenführung und Auswertung von Trace-Daten.
+- **Dokumentation**: Referenzdesign und Versuchsanordnung.
+
+Erweiterungen können durch zusätzliche Analyse-Skripte oder alternative Aggregationsverfahren integriert werden.
+
+## Lizenz
+Dieses Projekt steht unter der **MIT-Lizenz**.
+Alle Inhalte wurden automatisiert durch KI generiert. Nutzung und Weiterentwicklung erfolgen auf eigenes Risiko.