Add README.md

README.md

@@ -0,0 +1,104 @@
+# Host vs VM Correlation Analysis
+
+## Überblick
+Dieses Repository dokumentiert das Experiment **host_vs_vm_correlation_analysis**. Es untersucht Leistungs- und Verhaltensunterschiede zwischen Host- und Virtual-Machine-Umgebungen anhand einer Correlation-ID. Der Fokus liegt auf der Analyse des TTWU-Mechanismus (try_to_wake_up) und der Auswertung der zugehörigen wake_flags.
+
+Mehr Informationen im Artikel: [https://donau2space.de/tag-98-1731-weihnachtsklarheit-ueber-passau-eine-correlation-id-zieht-ttwu-auseinander-host-vs-vm/](https://donau2space.de/tag-98-1731-weihnachtsklarheit-ueber-passau-eine-correlation-id-zieht-ttwu-auseinander-host-vs-vm/)
+
+### 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
+
+### 1. correlation_id_generation
+- **Art:** Python-Skript  
+- **Ziel:** Linux Userspace  
+- **Sprachen:** Python  
+- **Zweck:** Generierung und Nachverfolgung einer Correlation-ID über mehrere Systemaufrufe zur Zuordnung von Host- und VM-Ereignissen.  
+
+**API-Funktionen:**
+- `generate_correlation_id(tgid, pid, run_seq)` → Erzeugt eine eindeutige Correlation-ID auf Basis von Prozessparametern.
+- `log_task_state(task, state_before, state_after)` → Protokolliert Zustandsänderungen eines Tasks.
+
+**Datenstruktur:**
+- `CorrelationData` (JSON): Felder – correlation_id, tgid, pid, timestamp
+
+---
+
+### 2. ttwu_analysis
+- **Art:** Python-Skript  
+- **Ziel:** Linux Userspace  
+- **Sprachen:** Python  
+- **Zweck:** Analyse von TTWU-Stacks und wake_flags zur Ermittlung von Differenzen im Scheduling-Verhalten zwischen Host und VM.  
+
+**API-Funktionen:**
+- `analyze_ttwu_stacks(host_data, vm_data)` → Führt eine Cluster-basierte Analyse von TTWU-Stacks durch und liefert Abweichungsmetriken.
+
+**Datenstruktur:**
+- `StackAnalysisResult` (JSON): Felder – cluster_a, cluster_b, offset
+
+---
+
+### 3. trace_aggregator
+- **Art:** Python-Skript  
+- **Ziel:** Linux Userspace  
+- **Sprachen:** Python  
+- **Zweck:** Aggregation von TTWU-Traces basierend auf wake_flags zur Vereinfachung der statistischen Auswertung.  
+
+**API-Funktionen:**
+- `aggregate_traces(trace_data, wake_flags)` → Aggregiert Trace-Daten nach bestimmten wake_flags-Kriterien und liefert ein konsolidiertes Analyseobjekt.
+
+**Datenstruktur:**
+- `TraceData` (JSON): Felder – trace_id, flags, timestamp
+
+---
+
+## Installation & Nutzung
+
+Voraussetzungen:
+- Linux-Umgebung mit Python ≥ 3.8
+- Zugriff auf entsprechende Trace-Daten (Host und VM)
+
+### Installation
+1. Klonen des Repositories:
+   ```bash
+   git clone https://github.com/example/host_vs_vm_correlation_analysis.git
+   cd host_vs_vm_correlation_analysis
+   ```
+2. Abhängigkeiten installieren:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+### Beispielausführung
+```bash
+python correlation_id_generation.py
+python ttwu_analysis.py --host host_trace.json --vm vm_trace.json
+python trace_aggregator.py --input traces.json --flags wake_flags.cfg
+```
+
+---
+
+## Typische Use-Cases
+- Vergleich von Scheduling-Latenzen zwischen Host und VM.
+- Untersuchung von Wakeup-Sequenzen mithilfe von Correlation-IDs.
+- Analyse und Clustering von TTWU-Stacks.
+- Aggregation von Trace-Daten aus mehreren Quellen.
+
+---
+
+## Struktur & mögliche Erweiterungen
+- Erweiterbar um Kernelmodul-Unterstützung für direkte Trace-Erfassung.
+- Integration von grafischen Analysemodulen oder Dashboards möglich.
+- Erweiterung der API um Live-Monitoring-Schnittstellen.
+
+---
+
+## Lizenz
+Dieses Projekt steht unter der **MIT-Lizenz**.
+
+**Haftungsausschluss:** Alle Inhalte wurden automatisch von einer KI generiert. Nutzung und Weiterentwicklung erfolgen auf eigenes Risiko. Keine Gewährleistung für Funktion, Genauigkeit oder rechtliche Verwendbarkeit.