Add README.md

README.md

@@ -0,0 +1,80 @@
+# N40 Read Analysis
+
+## Überblick
+Das Experiment **n40_read_analysis** untersucht die Performance von pinned und unpinned Reads im N40-Szenario. Ziel ist die Erfassung und Auswertung von Retry-freien Reads sowie deren Klassifikation nach Latenz und Erfolgsquote über verschiedene Laufkonfigurationen hinweg.
+
+[Artikel zum Experiment](https://donau2space.de/tag-124-1303-klarer-himmel-ueber-passau-und-ich-friere-mein-n40-run-set-wirklich-ein/)
+
+[Git-Repository](https://git.donau2space.de/Mika/n40_read_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
+Das Repository enthält Python-Skripte zur Analyse und Aggregation von Read-Performance-Daten. Sie dienen der Verarbeitung von Rohdaten, Erstellung von Summaries und Export in verschiedene Formate zur weiteren Auswertung.
+
+### Artefakte
+
+#### trace_aggpy
+- **Art:** python_script  
+- **Ziel:** Linux-Userspace  
+- **Sprachen:** Python  
+- **Zweck:** Analyse von Read-Events in Zeitfenstern und Erzeugung komprimierter Ergebnis-JSONs.
+
+**API-Funktionen:**
+- `analyze_reads(corr_id, read_data)` – Führt die Analyse der Reads durch und liefert strukturierte Ergebnis-Summaries zurück.
+
+**Datenstrukturen:**
+- `ReadAnalysisResult` (JSON) mit den Feldern `corr_id`, `retry_free_count`, `duration_metrics`, `summary_table`.
+
+#### run_summary_export
+- **Art:** python_script  
+- **Ziel:** Linux-Userspace  
+- **Sprachen:** Python  
+- **Zweck:** Export von Analyse- und Laufdaten in CSV- oder JSON-Format zur weiteren Verarbeitung.
+
+**API-Funktionen:**
+- `export_summary(summary_data, format)` – Exportiert einen Summary-Datensatz in das angegebene Format.
+
+**Datenstrukturen:**
+- `RunSummary` (JSON) mit den Feldern `run_id`, `p95`, `p99`, `retry_free_count`, `publish_reorder_count`.
+
+## Installation & Nutzung
+Die Skripte setzen eine Python-Umgebung (ab Version 3.8) voraus.
+
+### Installation
+- Repository klonen:  
+  `git clone https://git.donau2space.de/Mika/n40_read_analysis`
+- Verzeichnis wechseln:  
+  `cd n40_read_analysis`
+- Abhängigkeiten installieren (falls vorhanden):  
+  `pip install -r requirements.txt`
+
+### Nutzung
+Die Skripte können direkt auf der Kommandozeile ausgeführt oder in bestehende Analysepipelines eingebunden werden.
+
+Beispiel (Analyselauf):
+```
+python trace_aggpy input/traces.json output/summary.json
+```
+Beispiel (Exportlauf):
+```
+python run_summary_export output/summary.json export/run_results.csv
+```
+
+## Typische Use-Cases
+- Vergleich pinned vs. unpinned Read-Latenzen
+- Analyse retry-freier Reads in N40-Testläufen
+- Erstellung von Summary-Berichten aus Rohdaten
+- Automatisierter Export der Ergebnisse zur Visualisierung oder Archivierung
+
+## Struktur & Erweiterungen
+Die Codebasis ist modular aufgebaut. Neue Analysefunktionen können über ergänzende Python-Module hinzugefügt werden. Schnittstellen zwischen Analyse (trace_aggpy) und Export (run_summary_export) sind JSON-basiert und ermöglichen leichte Erweiterbarkeit.
+
+## Lizenz
+Dieses Projekt steht unter der **MIT-Lizenz**.
+
+---
+Diese README wurde automatisch von einer KI generiert. Nutzung und Interpretation erfolgen auf eigenes Risiko.