AV Chaos Monkey

Verteilte Chaos-Engineering-Plattform zum Lasttest von Videokonferenzsystemen. Simuliert 1500+ WebRTC-Teilnehmer mit H.264/Opus-Streams und injiziert Netzwerk-Chaos-Spitzen, um die Systemresilienz unter verschlechterten Bedingungen zu validieren.

Architektur

1. Medienverarbeitungspipeline:

   • FFmpeg konvertiert eingehendes Video beim Start in H.264 Annex-B und Ogg/Opus
   • NAL-Reader analysiert den H.264-Stream (SPS/PPS/IDR/Slices)
   • Opus-Reader extrahiert 20ms-Audioframes aus dem Ogg-Container
   • Frames werden im Cache gespeichert und von allen Teilnehmern gemeinsam genutzt (Zero-Copy)
   • Reduziert CPU um ~90 % im Vergleich zur Kodierung pro Teilnehmer

2. Steuerungsebene:

   • HTTP-Server (:8080) verwaltet den Testlebenszyklus über REST-API
   • Spike-Scheduler verteilt Chaos-Ereignisse (gerade/zufällig/vorne/hinten/legacy)
   • Network-Degrader wendet Chaos an: Paketverlust (1–25%), Jitter (10–50ms), Bitratenreduzierung (30–80%), Frame-Verluste (10–60%)
   • Geladene Chaos-Konfiguration wird auf den Teilnehmerpool angewendet

3. Teilnehmerpool:

   • Automatische Partitionierung über Pods mittels: participant_id % total_partitions = partition_id
   • Jeder Teilnehmer erzeugt RTP-Streams (PT=96 Video, PT=111 Audio)
   • Teilnehmer-ID eingebettet in RTP-Erweiterungsheader (ID=1)
   • Poolgröße: 1–100 (lokal), 100–500 (Docker), 500–1500 (Kubernetes)

4. Kubernetes-Autokonfiguration:

   • Pods erkennen automatisch die Partitions-ID aus dem Pod-Namen: orchestrator-3 → PARTITION_ID=3
   • Port-Zuweisung: base_port + (partition_id × 10000) + participant_index
   • Beispiel: Partition 0 verwendet 5000–14999, Partition 1 verwendet 15000–24999
   • StatefulSet mit 10 Replikaten, jedes handhabt ~150 Teilnehmer
   • Ressourcen: 1–4 CPU, 2–4Gi Speicher pro Pod
   • Automatische Konfiguration basierend auf den Spezifikationen des Host-Rechners

5. UDP-Relay-Kette (nur Kubernetes):

   root@kitploit:~

   Orchestrator-Pods (10×) → UDP :5000 → udp-relay-Pod (Python)
   → Längenpräfix-TCP :5001 → kubectl port-forward 15001:5001
   → tools/udp-relay (Go) → UDP :5002 → Ihr Empfänger
   

   • Warum: kubectl port-forward unterstützt nur TCP, nicht UDP
   • Relay im Cluster: Python-Skript aggregiert UDP von allen Pods, streamt als TCP mit 2-Byte-Längenpräfix
   • Lokales Relay: Go-Tool wandelt TCP-Stream zurück in UDP-Pakete
   • Aggregiert 1500 Teilnehmer-Streams in eine einzige Verbindung

6. WebRTC-Infrastruktur:

   • Coturn-StatefulSet: 3 anfängliche Replikate, HPA skaliert 1–10 basierend auf Last (~500 Teilnehmer/Replikat)
   • coturn-lb-Service: Lastverteilung des TURN-Traffics auf Replikate
   • webrtc-connector: Optionale Proxy-Schicht (Deployment + HPA 2–10 Replikate), behandelt SDP-Signalisierung
   • Docker-Modus: Einzelner Coturn-Container für lokale Tests
   • Ports: 3478 (TURN), 49152–65535 (Relay-Bereich)
   • Anmeldedaten: webrtc/webrtc123

7. Client-Integration:

   • UDP-Empfänger: Empfängt aggregierten RTP-Stream von allen Teilnehmern über die Relay-Kette
   • WebRTC-Empfänger: Stellt 1:1-WebRTC-Verbindungen über SDP-Austausch über TURN-Server her
   • Beide leiten an Ihr zu testendes Videokonferenzsystem weiter (SFU/MCU/Mesh)

8. Observability-Stack (optional):

   • Prometheus: Sammelt alle 5s den /metrics-Endpunkt von allen Orchestrator-Pods
   • Grafana: Visualisiert Metriken über ein vorkonfiguriertes Dashboard (admin/admin)
   • Verfügbare Metriken: Teilnehmeranzahl, gesendete Pakete, gesendete Bytes, aktive Spitzen, Paketverlust %, Jitter, MOS-Score
   • Zugriff: Prometheus auf :30090, Grafana auf :30030 (NodePort)
   • Orchestrator-Pods mit Anmerkungen für automatische Erkennung: prometheus.io/scrape: "true"

Grundlegende Konzepte

Teilnehmersimulation

Jeder virtuelle Teilnehmer erzeugt echte Medienströme:

• Video: H.264-NAL-Einheiten aus tatsächlichen Videodateien, paketisiert gemäß RFC 6184
• Audio: Opus-Frames aus Ogg-Containern, paketisiert gemäß RFC 7587
• RTP: Standardkonforme Header mit Teilnehmer-ID-Erweiterungen
• Timing: Frame-genaues Timing (30fps Video, 20ms Audio-Pakete)

Chaos-Injektion

Fünf Spitzentypen simulieren reale Netzwerkbedingungen:

• Paketverlust: Verwirft RTP-Pakete auf Anwendungsebene (1–100%)
• Netzwerk-Jitter: Fügt Latenzvariation hinzu (Basis + Gauß-Jitter)
• Bitratenreduzierung: Drosselt die Videokodierung (30–80 % Reduzierung)
• Frame-Verlust: Überspringt Videoframes (10–60 % Verlustrate)
• Bandbreitenbegrenzung: Deckelt den Gesamtdurchsatz

Verteilungsstrategien

Spitzen werden über die Testdauer mit konfigurierbaren Strategien verteilt:

• Even: Gleichmäßige Abstände mit Jitter (vorhersagbare Last)
• Random: Unvorhersehbare Zeitpunkte (realistisches Chaos)
• Front-loaded: Dichte Spitzen zu Beginn (Wiederherstellungstests)
• Back-loaded: Grundlinie gefolgt von Chaos (Vergleichstests)
• Legacy: Ticker mit festem Intervall (Laufzeit-Injektion)

Partitionierung

Kubernetes-Bereitstellungen verwenden Teilnehmerpartitionierung für horizontale Skalierung:

• Jeder Pod behandelt participant_id % total_partitions == partition_id
• Port-Zuweisung: base_port + (partition_id * 10000) + participant_index
• Automatische Lastverteilung auf 1–10 Pods
• Skaliert auf 1500+ Teilnehmer (150 pro Pod)

Das System ausführen

1. Lokale Entwicklung (Natives Go)

Am besten geeignet für: Entwicklung, Debugging, Kleintests (1–100 Teilnehmer)

# Orchestrator starten
go run cmd/main.go

# In einem anderen Terminal: UDP-Empfänger starten
go run examples/go/udp_receiver.go 5002

# config/config.json bearbeiten und num_participants: 10 setzen
# Chaos-Test ausführen
go run tools/chaos-test/main.go -config config/config.json

Was passiert:

• Ein einzelner Orchestrator-Prozess auf :8080
• Teilnehmer senden UDP an 127.0.0.1:5002
• Chaos-Spitzen werden über HTTP-API injiziert
• Echtzeit-Metriken werden alle 2s angezeigt

Konfiguration (config/config.json):

{
  "base_url": "http://localhost:8080",
  "media_path": "public/rick-roll.mp4",
  "num_participants": 10,
  "duration_seconds": 300,
  "spikes": {
    "count": 20,
    "interval_seconds": 5,
    "types": { "rtp_packet_loss": {...}, "network_jitter": {...} }
  },
  "spike_distribution": {
    "strategy": "random",
    "min_spacing_seconds": 5,
    "jitter_percent": 15
  }
}

2. Docker Compose (Containerisiert)

Am besten geeignet für: Isolierte Tests, CI/CD, mittlere Tests (100–500 Teilnehmer)

Voraussetzungen:

• Docker Desktop mit 8–16 GB Speicherzuweisung
• docker-compose installiert

# Orchestrator-Container bauen und starten
./scripts/start_everything.sh build

# In einem anderen Terminal: UDP-Empfänger starten
go run examples/go/udp_receiver.go 5002

# config/config.json bearbeiten und num_participants: 100 setzen
# Chaos-Test ausführen (zielt auf Container)
go run tools/chaos-test/main.go -config config/config.json

Ressourcenlimits (docker-compose.yaml bearbeiten):

services:
  orchestrator:
    deploy:
      resources:
        limits:
          cpus: "14.0"
          memory: 6G  # Für mehr Teilnehmer erhöhen

Skalierungsleitfaden:

3. Kubernetes mit Nix (Produktionsmaßstab)

Am besten geeignet für: Großtests (500–1500 Teilnehmer), horizontale Skalierung, Produktionsvalidierung

Voraussetzungen:

• Nix mit aktivierten Flakes
• Docker Desktop oder kind-Cluster
• kubectl konfiguriert

Schritt 1: Nix-Umgebung betreten

# Nix bietet: Go, Docker, kubectl, kind, ffmpeg
nix develop

# Oder direnv für automatische Aktivierung verwenden
echo "use flake" > .envrc
direnv allow

Schritt 2: In Kubernetes bereitstellen

# Automatische Bereitstellung mit optimalen Einstellungen (erkennt Systemressourcen)
./scripts/start_everything.sh run -config config/config.json

# Oder benutzerdefinierte Mediendateien angeben
./scripts/start_everything.sh run --media=path/to/video.mp4 -config config/config.json

Was passiert:

1. Baut Docker-Image mit der von Nix bereitgestellten Go-Toolchain
2. Erstellt/verwendet kind-Cluster
3. Stellt StatefulSet mit 10 Orchestrator-Pods bereit
4. Stellt UDP-Relay-Pod bereit
5. Richtet kubectl port-forward für das UDP-Relay ein
6. Startet lokales TCP→UDP-Relay
7. Führt Chaos-Test auf allen Pods aus

Schritt 3: Aggregierten UDP-Stream empfangen

Option A: UDP-Empfänger (Empfohlen für Kubernetes)

# Empfängt aggregierten Stream von allen 1500 Teilnehmern
go run ./examples/go/udp_receiver.go 5002

Option B: WebRTC-Empfänger (Mehrere Teilnehmer)

# Verbindung mit bis zu 150 Teilnehmern über WebRTC
go run ./examples/go/webrtc_receiver.go http://localhost:8080 <test_id> 150

Architektur-Fluss:

1500 Teilnehmer über 10 Pods
  → Jeder Pod: 150 Teilnehmer
  → Partitionierung nach participant_id % 10
  → Alle senden UDP an udp-relay:5000
  → UDP-Relay aggregiert → TCP :5001
  → kubectl port-forward 15001:5001
  → Lokales Relay wandelt TCP → UDP :5002
  → Ihr Empfänger erhält alle 1500 Streams

Hinweis: Das Skript start_everything.sh richtet automatisch ein:

• kubectl port-forward (udp-relay 15001:5001)
• Lokales TCP→UDP-Relay (tools/udp-relay)
• Sie müssen nur den Empfänger ausführen

Manuelle Kubernetes-Einrichtung

# Image bauen und laden
docker build -t chaos-monkey-orchestrator:latest .
kind load docker-image chaos-monkey-orchestrator:latest

# Bereitstellen
kubectl apply -f k8s/orchestrator/orchestrator.yaml
kubectl apply -f k8s/udp-relay/udp-relay.yaml

# Auf Pods warten
kubectl wait --for=condition=ready pod -l app=orchestrator --timeout=300s

# Port-Forward für UDP-Relay
kubectl port-forward udp-relay 15001:5001 &

# Lokales TCP→UDP-Relay starten
go run tools/udp-relay/main.go &

# In einem anderen Terminal: Empfänger starten
go run ./examples/go/udp_receiver.go 5002

# In einem anderen Terminal: Chaos-Test ausführen
go run tools/chaos-test/main.go -config config/config.json

Bereinigung

# Kubernetes-Ressourcen löschen
./scripts/cleanup.sh

# Oder gesamten Cluster löschen
kind delete cluster --name av-chaos-monkey

Plattformübergreifende Builds mit Nix

# Für Linux x86_64 bauen (am häufigsten)
nix build .#packages.x86_64-linux.av-chaos-monkey

# Für ARM64 bauen (Raspberry Pi, AWS Graviton)
nix build .#packages.aarch64-linux.av-chaos-monkey

# Für macOS Intel bauen
nix build .#packages.x86_64-darwin.av-chaos-monkey

# Für macOS Apple Silicon bauen
nix build .#packages.aarch64-darwin.av-chaos-monkey

# Binärdatei-Standort
./result/bin/main

API-Referenz

Testlebenszyklus

# Test erstellen
POST /api/v1/test/create
{
  "test_id": "optional_id",
  "num_participants": 100,
  "video": {...},
  "audio": {...},
  "duration_seconds": 600,
  "spikes": [...],
  "spike_distribution": {
    "strategy": "even",
    "min_spacing_seconds": 5,
    "jitter_percent": 15
  }
}

# Test starten
POST /api/v1/test/{test_id}/start

# Metriken abrufen
GET /api/v1/test/{test_id}/metrics

# Test stoppen
POST /api/v1/test/{test_id}/stop

WebRTC-Signalisierung

# SDP-Angebot abrufen
GET /api/v1/test/{test_id}/sdp/{participant_id}

# SDP-Antwort setzen
POST /api/v1/test/{test_id}/sdp/{participant_id}
{"sdp_answer": "v=0..."}

Chaos-Injektion

# Spike injizieren
POST /api/v1/test/{test_id}/spike
{
  "spike_id": "unique_id",
  "type": "rtp_packet_loss",
  "duration_seconds": 30,
  "participant_ids": [1001, 1002],
  "params": {"loss_percentage": "15"}
}

Konfiguration

Spike-Typen

Verteilungskonfiguration

{
  "spike_distribution": {
    "strategy": "even",
    "min_spacing_seconds": 5,
    "jitter_percent": 15,
    "respect_min_offset": true
  }
}

Client-Integration

UDP-Empfänger (Go)

# Mitgelieferter Empfänger mit RTP-Parsing
go run examples/go/udp_receiver.go 5002

Ausgabe:

Listening for RTP packets on UDP port 0.0.0.0:5002
Packet #100 from 127.0.0.1:xxxxx:
  Participant ID: 1001
  Payload Type: 96 (H.264 video)
  Sequence: 1234
  Timestamp: 90000
  SSRC: 1001000
  Payload Size: 1200 bytes

═══════════════════════════════════════════════════════════
                    PACKET STATISTICS                       
═══════════════════════════════════════════════════════════
Duration: 60s
Total Packets: 180000 (3000 pkt/s)
Total Bytes: 450 MB (60 Mbps)

Media Type Breakdown:
  Video (H.264): 120000 packets (66.7%)
  Audio (Opus):  60000 packets (33.3%)

Unique Streams (SSRCs): 1500
Unique Participants: 1500

WebRTC-Empfänger (Go)

# Einzelner Teilnehmer
go run ./examples/go/webrtc_receiver.go http://localhost:8080 <test_id>

# Mehrere Teilnehmer (bis zu 150)
go run ./examples/go/webrtc_receiver.go http://localhost:8080 <test_id> 150

# Beispiel mit tatsächlicher Test-ID
go run ./examples/go/webrtc_receiver.go http://localhost:8080 chaos_test_1770831684 150

Hinweis: WebRTC erfordert 1:1-Verbindungen. Für Kubernetes verwenden Sie den UDP-Empfänger, der alle Teilnehmer automatisch aggregiert.

Benutzerdefinierte Integration

RTP-Paketformat:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|V=2|P|X|  CC   |M|     PT      |       sequence number         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           timestamp                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|           synchronization source (SSRC) identifier            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  Extension ID=1 | Length=4    |    Participant ID (uint32)    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         H.264/Opus Payload                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Payload-Typen:

• 96: H.264-Video (RFC 6184)
• 111: Opus-Audio (RFC 7587)

Extraktion der Teilnehmer-ID:

// Extension bit set?
if (packet[0] & 0x10) != 0 {
    offset := 12 + int(packet[0]&0x0F)*4  // Skip CSRC
    extID := binary.BigEndian.Uint16(packet[offset:])
    if extID == 1 {
        participantID := binary.LittleEndian.Uint32(packet[offset+4:])
    }
}

Leistung

Ressourcenanforderungen

Kubernetes-Skalierung

• Auto-Skalierung: Berechnet optimale Pod-Anzahl basierend auf Teilnehmeranzahl
• Pod-Kapazität: 150 Teilnehmer pro Pod (konfigurierbar)
• Max. Pods: 10 (StatefulSet-Limit)
• Port-Bereich: 10.000 Ports pro Partition

Durchsatz

Pro Teilnehmer (1280x720@30fps + Opus):

• Video: ~2,5 Mbps (H.264)
• Audio: ~128 Kbps (Opus)
• Gesamt: ~2,6 Mbps
• Pakete: ~90 Video + 50 Audio = 140 pkt/s

Überwachung

Prometheus-Metriken

# Verfügbar unter /metrics-Endpunkt
av_chaos_monkey_participants_total
av_chaos_monkey_packets_sent_total
av_chaos_monkey_bytes_sent_total
av_chaos_monkey_spikes_active
av_chaos_monkey_packet_loss_percent
av_chaos_monkey_jitter_ms

Grafana-Dashboard

# Docker-Modus: Monitoring-Stack starten
docker-compose --profile monitoring up

# Kubernetes-Modus: Monitoring bereitstellen
kubectl apply -f k8s/monitoring/prometheus-rbac.yaml
kubectl apply -f k8s/monitoring/prometheus.yaml
kubectl apply -f k8s/monitoring/grafana.yaml

# Auf Grafana zugreifen
# Docker: http://localhost:3000
# Kubernetes: http://localhost:30030 (NodePort)
# Standard-Anmeldedaten: admin/admin

# Auf Prometheus zugreifen
# Docker: http://localhost:9091
# Kubernetes: http://localhost:30090 (NodePort)

Automatische Erkennung in Kubernetes:

• Orchestrator-Pods mit Anmerkung prometheus.io/scrape: "true"
• Prometheus sammelt alle 5s /metrics von allen Pods
• Grafana mit Prometheus-Datenquelle vorkonfiguriert
• Dashboard wird beim Start automatisch bereitgestellt

Echtzeit-Statistiken

# Test-Metriken abrufen
curl http://localhost:8080/api/v1/test/{test_id}/metrics | jq

# Ausgabe
{
  "aggregate": {
    "total_frames_sent": 45000,
    "total_packets_sent": 180000,
    "total_bitrate_kbps": 250000,
    "avg_jitter_ms": 12.5,
    "avg_packet_loss": 2.3,
    "avg_mos_score": 4.1
  }
}

Fehlerbehebung

Keine UDP-Pakete empfangen

# UDP-Zielkonfiguration prüfen
kubectl logs orchestrator-0 | grep "UDP transmission enabled"

# Prüfen, ob UDP-Relay läuft
kubectl get pod udp-relay

# Port-Forward prüfen
ps aux | grep "kubectl port-forward"

# UDP-Konnektivität testen
nc -u -z localhost 5002

WebRTC-Verbindung schlägt fehl

# TURN-Server prüfen
kubectl get svc coturn-lb

# ICE-Kandidaten prüfen
kubectl logs orchestrator-0 | grep "ICE"

# TURN-Konnektivität testen
turnutils_uclient -v -u webrtc -w webrtc123 <turn-server>:3478

Hohe Speichernutzung

# Teilnehmeranzahl pro Pod prüfen
kubectl exec orchestrator-0 -- curl -s http://localhost:8080/api/v1/test/{test_id}/metrics | jq '.participants | length'

# Teilnehmeranzahl reduzieren oder Pod-Anzahl erhöhen
go run tools/k8s-start/main.go -replicas 10 -participants 1000

# Docker-Speicher erhöhen (Docker Desktop)
# Einstellungen → Ressourcen → Speicher → 16GB

Paketverlust im UDP-Empfänger

Ein einzelner UDP-Socket kann 3000+ gleichzeitige Streams ohne Kernel-Pufferüberlauf nicht verarbeiten. Lösungen:

• UDP-Relay verwenden (aggregiert vor der Weiterleitung)
• Socket-Puffer erhöhen: setsockopt(SO_RCVBUF, 8MB)
• Basisverlust als Messartefakt akzeptieren

Lizenz

BSD 3-Clause License

Mitwirken

Beiträge willkommen! Schlüsselbereiche:

• Zusätzliche Spike-Typen (CPU-Drosselung, Speicherdruck)
• Weitere Verteilungsstrategien (Welle, Burst)
• Erweiterte Metriken (MOS-Berechnung, RTCP-Feedback)
• Client-Bibliotheken (Python, Rust, TypeScript)

Referenzen

• RFC 3550 - RTP: A Transport Protocol for Real-Time Applications
• RFC 6184 - RTP Payload Format for H.264 Video
• RFC 7587 - RTP Payload Format for Opus
• WebRTC Specification