XC_VM/docs/ru/development/streaming-diagnostics.md

# Потоковая диагностика и инструменты

Отдельный инструмент проверяет правильность доставки потока — что сегменты поступают по порядку и очередь доставки не прерывается. Это не зависит от пути запроса; об этом смотрите в [Подсистеме потоковой передачи](streaming-subsystem.md).

---

## `tools/stream-check/stream_check.py` (Только Python, stdlib)

Единый инструмент без зависимостей, который обеспечивает потоковую передачу данных **проверяет** и вывод результата **рендеры** в формате SVG. Автоматически определяет значения HLS и MPEG-TS. Три подкоманды:

|Подкомандование|Цель|
| --- | --- |
| `check <url>` |проверьте один поток (или посмотрите его в прямом эфире с помощью `--live`)|
|`список воспроизведения <путь\|url>`|протестируйте каждый поток в списке каналов `.m3u` → агрегируйте JSON (+ файлы для каждого потока)|
| `graph <inputs…>` |визуализируйте JSON из `check`/`playlist` в виде статических SVG-диаграмм|

```bash
python3 tools/stream-check/stream_check.py check "<url>" --duration 30        # batch check
python3 tools/stream-check/stream_check.py check "<url>" --json               # cron / monitoring
python3 tools/stream-check/stream_check.py check "<url>" --live --duration 0  # live dashboard
python3 tools/stream-check/stream_check.py playlist list.m3u --out-dir logs/  # batch a whole playlist
python3 tools/stream-check/stream_check.py graph logs/ --combined            # JSON → SVG charts
```

Что означает "неповрежденная очередь" для каждого типа потока:

|Течение|Проверка очереди|
| --- | --- |
|HLS (`.m3u8`)|`EXT-X-MEDIA-SEQUENCE` монотонный и непрерывный (никаких удаленных или перемотанных сегментов), нет `EXT-X-DISCONTINUITY`, каждый вновь появляющийся сегмент доступен для загрузки. Основные плейлисты отображаются в их первом варианте.|
|MPEG-TS (`.ts`, `/play/<token>/ts`)|per-PID `continuity_counter` (потерянные / дублированные / переупорядоченные пакеты = разрыв очереди), потеря байта синхронизации, индикатор транспортной ошибки и задержка доставки.|

Ключевые параметры `check`:

|Флаг|Цель|
| --- | --- |
| `--duration N` |секунды для наблюдения (`0` = до нажатия Ctrl-C в `--live`)|
| `--tolerance N` |разрешить N временных разрывов очереди, прежде чем сообщать о `BROKEN` (игнорируются редкие сбои источника, переданные `-c copy`)|
| `--stall-timeout S` |перерыв в доставке засчитывается как задержка; не превышайте продолжительность сегмента (по умолчанию 15).|
| `--live` |цветная приборная панель TUI (внизу)|
|`--prebuffer S` / `--buffer-target S`|live: предварительный буфер для виртуального игрока и масштаб буферного графика|
|`--json` / `--no-color`|машинный вывод / отключение ANSI|

Код выхода: `0` исправен, `2` проблема с очередью или задержка, `1` использование.

### Оперативная панель мониторинга (`--live`)

Моделирует виртуальный проигрыватель: проигрыватель перемещается со скоростью настенных часов, в то время как контент "принимается". Для **тс** полученная временная шкала отсчитывается от **ПЦР** (часы потоковой передачи); для **HLS** - от длительности сегментов `EXTINF`. Буферизованное время воспроизведения ("кэш") = получено − воспроизведено; если оно достигает нуля, начало воспроизведения зависает (событие отмены буферизации).

```text
  STREAM QUEUE / BUFFER MONITOR   TS   up 00:22
  cache buffer (s), last 60s:
  ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▄▄▄▇▇▇▆▆▆▅▅▅▄▄▇▇▇▆▆▆▅   <- burst-then-drain = delivery sawtooth
  IN CACHE : [█████████████████░░░░░░░░░░░░░]  11.6s / 20s
  PLAYING  : PLAYING     head 00:18   received 00:29
  rate 1000 kbit/s   received 4.1 MB   last data 7.0s ago
  QUEUE OK   cc:0 sync:0 gaps:0 disc:0   rebuffers:0
```

График буфера и индикатор окрашены в зеленый (работоспособный) / желтый (низкий) / красный (недостаточный) цвета. Для HLS ряд блоков показывает сегменты, которые все еще находятся в кэше перед началом воспроизведения.

> **Обратите внимание — темп доставки.** Оперативная доставка клиентов теперь осуществляется с помощью
> `xc_fanout` демон (см. [Streaming Subsystem → Daemon delivery](streaming-subsystem.md#daemon-delivery-xc_fanout)), который извлекает каждый исходный код один раз и передает его через сокет unix. `stream_check.py check --live` визуализирует поведение буфера, которое реальный игрок увидел бы при просмотре доставленного потока.

---

## Связанные файлы

|Файл|Цель|
| --- | --- |
| `tools/stream-check/stream_check.py` |проверка целостности очереди (`check`), пакетный список воспроизведения (`playlist`), панель мониторинга динамического буфера (`check --live`) и графический редактор SVG (`graph`)|