Skip to content

API

control.plane.api

Sapsan отдает состояние сервера по HTTP. API совместимо по формату с Flussonic Streamer API v3 — существующие интеграции продолжают работать.

Доступ

Доступ к API защищается логином и паролем в секции api_auth:

api_auth:
  login: admin
  password: secret

Эндпоинты

Базовый префикс — /streamer/api/v3:

Метод и путь Что возвращает
GET /streamer/api/v3/streams список потоков и их состояние
GET /streamer/api/v3/config текущая конфигурация сервера
GET /streamer/api/v3/dvrs список DVR-хранилищ
GET /streamer/api/v3/dvrs/{name} состояние конкретного DVR
GET /streamer/api/v3/rproxy состояние шлюза Peeklio и агентов
GET /streamer/api/v3/monitoring/readiness readiness-проба для оркестраторов

Нативное API v4

Развивающееся нативное API живет по префиксу /streamer/api-v4:

Путь Что возвращает
GET /listeners список слушателей
GET /streams, GET /streams/{name} потоки и их состояние
GET /streams/stats, GET /streams-stats статистика потоков
GET /sessions/stats статистика сессий
GET /live-metrics, GET /sessions-metrics метрики лайва и сессий
GET /dvr, GET /dvr/catalog, GET /dvr/metrics состояние DVR-хранилища и каталога
POST /dvr/rebuild-index, GET (статус), DELETE (остановить) перестройка каталога с дисков
POST /dvr/cleanup, GET /dvr/cleanup запустить очистку архива / статус
GET /runtime/metrics метрики процесса в формате Prometheus
GET /auth состояние авторизации
GET /license/status состояние лицензии
GET /rproxy/streampoint-agents агенты шлюза Peeklio

Note

TODO: примеры ответов, управление потоками через API (когда появится запись).

Что дальше

Доступ к Admin API

Admin API защищается отдельной секцией api_auth — см. Admin API.

Здоровье сервера

  • Readiness-проба: GET /streamer/api/v3/monitoring/readiness — для Kubernetes и балансировщиков.
  • Состояние потоков: GET /streamer/api/v3/streams.

Статы стрима в Admin API

Список стримов

GET /streamer/api-v4/streams/stats возвращает по элементу на стрим — этим списком живёт страница каналов в UI, и его же удобно опрашивать скриптами.

Поле Что означает Как использовать
status, status_since состояние стрима и момент перехода в него стрим не running дольше N минут — алерт
bitrate_kbit измеренный media-битрейт активного входа, по таймстемпам кадров просел заметно ниже номинала — источник деградировал. Это не сетевой throughput: файл может читаться быстрее реального времени
source.url вход, который играет фактически отличается от первого в конфиге — стрим живёт на резерве
inputs[] рантайм-статус каждого сконфигурированного входа: url, status, давность проверки checked_ago_ms, битрейт, текст ошибки см. ниже
dvr.from, dvr.to окно архива на этом сервере to отстаёт от текущего времени — запись остановилась; from перестал двигаться вперёд — не работает чистка, впереди переполнение диска
dvr.recorded_hours, dvr.bytes, dvr.periods итог архива: сколько часов записано, сколько места архив занимает на дисках и из скольких непрерывных участков состоит; обновляется раз в минуту, точность — час recorded_hours заметно меньше ширины окна to - from — в архиве дыры; bytes — место, которое стрим занимает на сервере
bytes_in, bytes_out кумулятивные счётчики байт с момента старта стрима для скоростей и истории используйте встроенный Prometheus-сервер или Retroview: снапшот обнуляется рестартом

Статусы элементов inputs[]:

  • active — играет сейчас;
  • ok — резерв, живой по последней проверке;
  • error — резерв с зафиксированной проблемой (текст — в error);
  • unchecked — резерв, который ещё ни разу не проверялся.

Это ответ на главный вопрос резервирования — «переключимся ли мы, когда упадёт основной». Резервы проверяются периодически (recheck_secondary_inputs_interval, см. резервные источники); алертить стоит и на error, и на unchecked, и на слишком старый checked_ago_ms — непроверенный резерв нельзя считать рабочим.

Один стрим

GET /streamer/api-v4/streams/stats/{name} добавляет к тем же полям диагностические секции — их нет в списке, чтобы список оставался дешёвым.

Секция input — счётчики текущего входа:

Поле Зачем
bytes, frames, bitrate_kbit вход вообще приносит данные, и с какой скоростью
retries переподключения к источнику: растёт — источник или сеть нестабильны
input_switches переключения между входами: растёт — вход флапает, разбирайтесь с основным
errors агрегатный счётчик ошибок входа: растёт — есть проблема; причина — в расширенных счётчиках или Retroview
num_sec_on_primary_input, num_sec_on_secondary_input сколько секунд прожили на основном и на резерве: заметная доля резерва — основной вход систематически плох
num_sec_no_data секунды без данных вовсе
errors_lost_packets, errors_connection_closed, errors_http_request_error, … причинная детализация ошибок — только с опцией «расширенные счётчики»

Секция dvr в единичном ответе дополняется:

Поле Зачем
write.segments_written, write.segments_failed, write.segments_skipped счётчики записи фрагментов: segments_failed растёт — архив теряет данные прямо сейчас, проверяйте диск
write.segments_written_slow / _delayed / _collapsed, write.segments_discontinuity профилирование записи — только с опцией «расширенные счётчики»

Note

Снапшот Admin API обнуляется рестартом сервера. Он отвечает на вопрос «что сейчас», но не годится ни для сверки счёта, ни для разбора вчерашнего инцидента — для этого есть Retroview.