XC_VM/docs/ru/development/streaming-diagnostics.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-диаграмм

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. Буферизованное время воспроизведения ("кэш") = получено − воспроизведено; если оно достигает нуля, начало воспроизведения зависает (событие отмены буферизации).

  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), который извлекает каждый исходный код один раз и передает его через сокет unix. stream_check.py check --live визуализирует поведение буфера, которое реальный игрок увидел бы при просмотре доставленного потока.

---

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

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