mdsadiqmd/av-chaos-monkeyChaos Monkey, но для тестирования аудио/видео (webRTC и UDP)
# AV Chaos Monkey
Распределенная платформа хаос-инжиниринга для нагрузочного тестирования систем видеоконференций. Симулирует 1500+ участников WebRTC с потоками H.264/Opus и инжектирует пики сетевого хаоса для проверки устойчивости системы в условиях деградации.
## Архитектура
<img width="1850" height="1776" alt="image" src="https://assets.kitploit.com/production/public/readmes/12084/a6658373be41c1a0480699e9caefe3a2f7bb0df85dc8731471fea315d9739429.png" />
1. **Конвейер обработки медиа**:
- FFmpeg конвертирует входное видео в H.264 Annex-B и Ogg/Opus при запуске
- NAL Reader парсит поток H.264 (SPS/PPS/IDR/Слайсы)
- Opus Reader извлекает 20-мс аудиофреймы из контейнера Ogg
- Фреймы кэшируются в памяти, совместно используются всеми участниками (zero-copy)
- Снижает загрузку CPU на ~90% по сравнению с кодированием для каждого участника
2. **Плоскость управления**:
- HTTP-сервер (:8080) управляет жизненным циклом теста через REST API
- Планировщик пиков (Spike Scheduler) распределяет события хаоса (равномерные/случайные/с фронтальной загрузкой/с тыловой загрузкой/унаследованные)
- Сетевой деградатор (Network Degrader) применяет хаос: потеря пакетов (1-25%), джиттер (10-50 мс), снижение битрейта (30-80%), пропуск кадров (10-60%)
- Загруженная конфигурация хаоса применяется к пулу участников
3. **Пул участников**:
- Автоматически разделяется между подами по формуле: `participant_id % total_partitions = partition_id`
- Каждый участник генерирует RTP-потоки (PT=96 видео, PT=111 аудио)
- ID участника встраивается в заголовок расширения RTP (ID=1)
- Размер пула: 1-100 (локально), 100-500 (Docker), 500-1500 (Kubernetes)
4. **Автоконфигурация Kubernetes**:
- Поды автоматически определяют ID раздела (partition ID) из имени пода: `orchestrator-3` → `PARTITION_ID=3`
- Выделение портов: `base_port + (partition_id × 10000) + participant_index`
- Пример: Раздел 0 использует 5000-14999, Раздел 1 использует 15000-24999
- StatefulSet с 10 репликами, каждая обрабатывает ~150 участников
- Ресурсы: 1-4 CPU, 2-4 ГБ памяти на под
- Автоконфигурация на основе характеристик хост-машины
5. **UDP-ретрансляционная цепочка** (только Kubernetes):
```
Поды-оркестраторы (10×) → UDP :5000 → Под udp-relay (Python)
→ TCP с префиксом длины :5001 → kubectl port-forward 15001:5001
→ tools/udp-relay (Go) → UDP :5002 → Ваш приёмник
```
- **Почему**: kubectl port-forward поддерживает только TCP, не UDP
- **Ретранслятор внутри кластера**: Python-скрипт агрегирует UDP со всех подов, передаёт как TCP с 2-байтовым префиксом длины
- **Локальный ретранслятор**: Go-утилита преобразует TCP-поток обратно в UDP-пакеты
- Агрегирует потоки 1500 участников в одно соединение
6. **Инфраструктура WebRTC**:
- **StatefulSet Coturn**: 3 начальные реплики, HPA масштабирует от 1 до 10 в зависимости от нагрузки (~500 участников/реплика)
- **Сервис coturn-lb**: Балансирует TURN-трафик между репликами
- **webrtc-connector**: Дополнительный прокси-слой (Deployment + HPA 2-10 реплик), обрабатывает SDP-сигнализацию
- **Режим Docker**: Один контейнер Coturn для локального тестирования
- Порты: 3478 (TURN), 49152-65535 (диапазон ретрансляции)
- Учётные данные: webrtc/webrtc123
7. **Интеграция с клиентом**:
- **UDP-приёмник**: Получает агрегированный RTP-поток от всех участников через ретрансляционную цепочку
- **WebRTC-приёмник**: Устанавливает соединения WebRTC 1:1 через обмен SDP через TURN-серверы
- Оба перенаправляют в тестируемую систему видеозвонков (SFU/MCU/Mesh)
8. **Стек наблюдаемости** (опционально):
- **Prometheus**: Собирает метрики с эндпоинта `/metrics` всех подов-оркестраторов каждые 5 с
- **Grafana**: Визуализирует метрики через предварительно настроенную панель (admin/admin)
- Доступные метрики: количество участников, отправленные пакеты, отправленные байты, активные пики, процент потери пакетов, джиттер, оценка MOS
- Доступ: Prometheus на :30090, Grafana на :30030 (NodePort)
- Поды-оркестраторы аннотированы для автообнаружения: `prometheus.io/scrape: "true"`
## Основные концепции
### Симуляция участников
Каждый виртуальный участник генерирует реальные медиапотоки:
- **Видео**: NAL-единицы H.264 из реальных видеофайлов, пакетизированные по RFC 6184
- **Аудио**: Фреймы Opus из контейнеров Ogg, пакетизированные по RFC 7587
- **RTP**: Заголовки, соответствующие стандарту, с расширениями ID участника
- **Тайминг**: Фрейм-точный тайминг (30 кадр/с видео, 20 мс аудиопакеты)
### Инжекция хаоса
Пять типов пиков симулируют реальные сетевые условия:
- **Потеря пакетов**: Отбрасывает RTP-пакеты на прикладном уровне (1-100%)
- **Сетевой джиттер**: Добавляет вариацию задержки (базовая + гауссов джиттер)
- **Снижение битрейта**: Ограничивает кодирование видео (снижение на 30-80%)
- **Пропуск кадров**: Пропускает видеокадры (10-60% пропуска)
- **Ограничение пропускной способности**: Ограничивает общую пропускную способность
### Стратегии распределения
Пики распределяются по длительности теста с помощью настраиваемых стратегий:
- **Равномерная (Even)**: Равномерные интервалы с джиттером (предсказуемая нагрузка)
- **Случайная (Random)**: Непредсказуемое время (реалистичный хаос)
- **С фронтальной загрузкой (Front-loaded)**: Частые пики в начале (тестирование восстановления)
- **С тыловой загрузкой (Back-loaded)**: Базовый уровень, затем хаос (сравнительное тестирование)
- **Унаследованная (Legacy)**: Таймер с фиксированным интервалом (инжекция во время выполнения)
### Разделение на партиции
В развёртываниях Kubernetes используется разделение участников на партиции для горизонтального масштабирования:
- Каждый под обрабатывает `participant_id % total_partitions == partition_id`
- Выделение портов: `base_port + (partition_id * 10000) + participant_index`
- Автоматическое распределение нагрузки между 1-10 подами
- Масштабируется до 1500+ участников (150 на под)
## Запуск системы
### 1. Локальная разработка (нативный Go)
**Лучше всего для**: Разработка, отладка, мелкомасштабные тесты (1-100 участников)
```bash
# Запуск оркестратора
go run cmd/main.go
# В другом терминале: Запуск UDP-приёмника
go run examples/go/udp_receiver.go 5002
# Отредактируйте config/config.json, установите num_participants: 10
# Запуск теста хаоса
go run tools/chaos-test/main.go -config config/config.json
```
**Что происходит:**
- Один процесс оркестратора на порту `:8080`
- Участники отправляют UDP на `127.0.0.1:5002`
- Пики хаоса инжектируются через HTTP API
- Метрики в реальном времени отображаются каждые 2 с
**Конфигурация** (`config/config.json`):
```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 (контейнеризированный)
**Лучше всего для**: Изолированное тестирование, CI/CD, средне-масштабные тесты (100-500 участников)
**Предварительные требования:**
- Docker Desktop с выделением 8-16 ГБ памяти
- Установленный `docker-compose`
```bash
# Сборка и запуск контейнера оркестратора
./scripts/start_everything.sh build
# В другом терминале: Запуск UDP-приёмника
go run examples/go/udp_receiver.go 5002
# Отредактируйте config/config.json, установите num_participants: 100
# Запуск теста хаоса (нацелен на контейнер)
go run tools/chaos-test/main.go -config config/config.json
```
**Ограничения ресурсов** (редактируйте `docker-compose.yaml`):
```yaml
services:
orchestrator:
deploy:
resources:
limits:
cpus: "14.0"
memory: 6G # Увеличьте для большего числа участников
```
**Руководство по масштабированию:**
| Память Docker | Макс. участников | Ядра CPU |
|--------------|------------------|-----------|
| 8 ГБ | ~100 | 4 |
| 16 ГБ | ~250 | 8 |
| 24 ГБ | ~400 | 12 |
| 32 ГБ | ~500 | 14 |
---
### 3. Kubernetes с Nix (производственный масштаб)
**Лучше всего для**: Крупномасштабные тесты (500-1500 участников), горизонтальное масштабирование, валидация в продакшене
**Предварительные требования:**
- Nix с включенными flakes
- Docker Desktop или кластер kind
- Настроенный kubectl
#### Шаг 1: Вход в окружение Nix
```bash
# Nix предоставляет: Go, Docker, kubectl, kind, ffmpeg
nix develop
# Или используйте direnv для автоактивации
echo "use flake" > .envrc
direnv allow
```
#### Шаг 2: Развёртывание в Kubernetes
```bash
# Авторазвёртывание с оптимальными настройками (обнаруживает системные ресурсы)
./scripts/start_everything.sh run -config config/config.json
# Или укажите собственные медиафайлы
./scripts/start_everything.sh run --media=path/to/video.mp4 -config config/config.json
```
**Что происходит:**
1. Собирается Docker-образ с использованием Go-инструментария из Nix
2. Создаётся/используется кластер kind
3. Развёртывается StatefulSet с 10 подами-оркестраторами
4. Развёртывается под UDP-ретранслятора
5. Настраивается `kubectl port-forward` для UDP-ретранслятора
6. Запускается локальный TCP→UDP ретранслятор
7. Выполняется тест хаоса на всех подах
#### Шаг 3: Приём агрегированного UDP-потока
**Вариант A: UDP-приёмник (рекомендуется для Kubernetes)**
```bash
# Получает агрегированный поток от всех 1500 участников
go run ./examples/go/udp_receiver.go 5002
```
**Вариант B: WebRTC-приёмник (множество участников)**
```bash
# Подключиться до 150 участников через WebRTC
go run ./examples/go/webrtc_receiver.go http://localhost:8080 <test_id> 150
```
**Архитектурный поток:**
```
1500 участников на 10 подах
→ Каждый под: 150 участников
→ Разделение по participant_id % 10
→ Все отправляют UDP на udp-relay:5000
→ UDP-ретранслятор агрегирует → TCP :5001
→ kubectl port-forward 15001:5001
→ Локальный ретранслятор преобразует TCP → UDP :5002
→ Ваш приёмник получает все 1500 потоков
```
**Примечание**: Скрипт `start_everything.sh` автоматически настраивает:
- kubectl port-forward (udp-relay 15001:5001)
- Локальный TCP→UDP ретранслятор (tools/udp-relay)
- Вам нужно только запустить приёмник
#### Ручная настройка Kubernetes
```bash
# Сборка и загрузка образа
docker build -t chaos-monkey-orchestrator:latest .
kind load docker-image chaos-monkey-orchestrator:latest
# Развёртывание
kubectl apply -f k8s/orchestrator/orchestrator.yaml
kubectl apply -f k8s/udp-relay/udp-relay.yaml
# Ожидание готовности подов
kubectl wait --for=condition=ready pod -l app=orchestrator --timeout=300s
# Проброс портов для UDP-ретранслятора
kubectl port-forward udp-relay 15001:5001 &
# Запуск локального TCP→UDP ретранслятора
go run tools/udp-relay/main.go &
# В другом терминале: Запуск приёмника
go run ./examples/go/udp_receiver.go 5002
# В другом терминале: Запуск теста хаоса
go run tools/chaos-test/main.go -config config/config.json
```
#### Очистка
```bash
# Удаление ресурсов Kubernetes
./scripts/cleanup.sh
# Или удаление всего кластера
kind delete cluster --name av-chaos-monkey
```
---
### Кроссплатформенная сборка с Nix
```bash
# Сборка для Linux x86_64 (самое распространённое)
nix build .#packages.x86_64-linux.av-chaos-monkey
# Сборка для ARM64 (Raspberry Pi, AWS Graviton)
nix build .#packages.aarch64-linux.av-chaos-monkey
# Сборка для macOS Intel
nix build .#packages.x86_64-darwin.av-chaos-monkey
# Сборка для macOS Apple Silicon
nix build .#packages.aarch64-darwin.av-chaos-monkey
# Расположение бинарного файла
./result/bin/main
```
## Справочник по API
### Жизненный цикл теста
```bash
# Создание теста
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
}
}
# Запуск теста
POST /api/v1/test/{test_id}/start
# Получение метрик
GET /api/v1/test/{test_id}/metrics
# Остановка теста
POST /api/v1/test/{test_id}/stop
```
### Сигнализация WebRTC
```bash
# Получение SDP-оффера
GET /api/v1/test/{test_id}/sdp/{participant_id}
# Установка SDP-ответа
POST /api/v1/test/{test_id}/sdp/{participant_id}
{"sdp_answer": "v=0..."}
```
### Инжекция хаоса
```bash
# Инжектировать пик
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"}
}
```
## Конфигурация
### Типы пиков
| Тип | Параметры | Эффект |
|------|-----------|--------|
| `rtp_packet_loss` | `loss_percentage` (0-100) | Отбрасывает пакеты на уровне RTP |
| `network_jitter` | `base_latency_ms`, `jitter_std_dev_ms` | Добавляет вариацию задержки |
| `bitrate_reduce` | `new_bitrate_kbps` | Ограничивает кодирование видео |
| `frame_drop` | `drop_percentage` (0-100) | Пропускает видеокадры |
| `bandwidth_limit` | `bandwidth_kbps` | Ограничивает общую пропускную способность |
### Конфигурация распределения
```json
{
"spike_distribution": {
"strategy": "even",
"min_spacing_seconds": 5,
"jitter_percent": 15,
"respect_min_offset": true
}
}
```
## Интеграция с клиентом
### UDP-приёмник (Go)
```bash
# Предоставленный приёмник с парсингом RTP
go run examples/go/udp_receiver.go 5002
```
**Вывод:**
```
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
═══════════════════════════════════════════════════════════
СТАТИСТИКА ПАКЕТОВ
═══════════════════════════════════════════════════════════
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-приёмник (Go)
```bash
# Один участник
go run ./examples/go/webrtc_receiver.go http://localhost:8080 <test_id>
# Несколько участников (до 150)
go run ./examples/go/webrtc_receiver.go http://localhost:8080 <test_id> 150
# Пример с реальным ID теста
go run ./examples/go/webrtc_receiver.go http://localhost:8080 chaos_test_1770831684 150
```
**Примечание**: WebRTC требует соединений 1:1. Для Kubernetes используйте UDP-приёмник, который автоматически агрегирует всех участников.
### Пользовательская интеграция
**Формат RTP-пакета:**
```
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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```
**Типы полезной нагрузки:**
- `96`: H.264 видео (RFC 6184)
- `111`: Opus аудио (RFC 7587)
**Извлечение ID участника:**
```go
// Установлен ли бит расширения?
if (packet[0] & 0x10) != 0 {
offset := 12 + int(packet[0]&0x0F)*4 // Пропустить CSRC
extID := binary.BigEndian.Uint16(packet[offset:])
if extID == 1 {
participantID := binary.LittleEndian.Uint32(packet[offset+4:])
}
}
```
## Производительность
### Требования к ресурсам
| Участники | Память | CPU | Пропускная способность |
|-------------|--------|-----|-----------|
| 100 | 2 ГБ | 2 ядра | 250 Мбит/с |
| 500 | 6 ГБ | 8 ядер | 1.2 Гбит/с |
| 1000 | 12 ГБ | 16 ядер | 2.5 Гбит/с |
| 1500 | 18 ГБ | 24 ядра | 3.7 Гбит/с |
### Масштабирование Kubernetes
- **Авто-масштабирование**: Вычисляет оптимальное количество подов на основе числа участников
- **Вместимость пода**: 150 участников на под (настраивается)
- **Макс. подов**: 10 (ограничение StatefulSet)
- **Диапазон портов**: 10 000 портов на партицию
### Пропускная способность
На одного участника (1280x720@30fps + Opus):
- Видео: ~2.5 Мбит/с (H.264)
- Аудио: ~128 Кбит/с (Opus)
- Всего: ~2.6 Мбит/с
- Пакетов: ~90 видео + 50 аудио = 140 пакетов/с
## Мониторинг
### Метрики Prometheus
```bash
# Доступны на эндпоинте /metrics
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
```bash
# Режим Docker: Запуск стека мониторинга
docker-compose --profile monitoring up
# Режим Kubernetes: Развёртывание стека мониторинга
kubectl apply -f k8s/monitoring/prometheus-rbac.yaml
kubectl apply -f k8s/monitoring/prometheus.yaml
kubectl apply -f k8s/monitoring/grafana.yaml
# Доступ к Grafana
# Docker: http://localhost:3000
# Kubernetes: http://localhost:30030 (NodePort)
# Учётные данные по умолчанию: admin/admin
# Доступ к Prometheus
# Docker: http://localhost:9091
# Kubernetes: http://localhost:30090 (NodePort)
```
**Автообнаружение в Kubernetes:**
- Поды-оркестраторы аннотированы `prometheus.io/scrape: "true"`
- Prometheus собирает метрики со всех подов каждые 5 с
- Grafana предварительно настроена с источником данных Prometheus
- Панель автоматически предоставляется при запуске
### Статистика в реальном времени
```bash
# Получение метрик теста
curl http://localhost:8080/api/v1/test/{test_id}/metrics | jq
# Вывод
{
"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
}
}
```
## Устранение неполадок
### UDP-пакеты не приходят
```bash
# Проверка конфигурации UDP-цели
kubectl logs orchestrator-0 | grep "UDP transmission enabled"
# Проверка работы UDP-ретранслятора
kubectl get pod udp-relay
# Проверка проброса портов
ps aux | grep "kubectl port-forward"
# Тестирование UDP-соединения
nc -u -z localhost 5002
```
### Сбой подключения WebRTC
```bash
# Проверка TURN-сервера
kubectl get svc coturn-lb
# Проверка ICE-кандидатов
kubectl logs orchestrator-0 | grep "ICE"
# Тестирование TURN-соединения
turnutils_uclient -v -u webrtc -w webrtc123 <turn-server>:3478
```
### Высокое использование памяти
```bash
# Проверка количества участников на под
kubectl exec orchestrator-0 -- curl -s http://localhost:8080/api/v1/test/{test_id}/metrics | jq '.participants | length'
# Уменьшение числа участников или увеличение количества подов
go run tools/k8s-start/main.go -replicas 10 -participants 1000
# Увеличение памяти Docker (Docker Desktop)
# Настройки → Ресурсы → Память → 16 ГБ
```
### Потеря пакетов в UDP-приёмнике
Один UDP-сокет не может обработать 3000+ одновременных потоков без переполнения буфера ядра. Решения:
- Используйте UDP-ретранслятор (агрегирует перед пересылкой)
- Увеличьте буфер сокета: `setsockopt(SO_RCVBUF, 8MB)`
- Примите базовую потерю как артефакт измерения
## Лицензия
BSD 3-Clause License
## Вклад
Приветствуются вклады! Ключевые области:
- Дополнительные типы пиков (троттлинг CPU, нагрузка на память)
- Больше стратегий распределения (волна, всплеск)
- Расширенные метрики (расчёт MOS, обратная связь RTCP)
- Клиентские библиотеки (Python, Rust, TypeScript)
## Ссылки
- [RFC 3550](https://tools.ietf.org/html/rfc3550) - RTP: A Transport Protocol for Real-Time Applications
- [RFC 6184](https://tools.ietf.org/html/rfc6184) - RTP Payload Format for H.264 Video
- [RFC 7587](https://tools.ietf.org/html/rfc7587) - RTP Payload Format for Opus
- [WebRTC Specification](https://www.w3.org/TR/webrtc/)