Skip to content

API

control.plane.api

O Sapsan expõe o estado do servidor por HTTP. A API é compatível em formato com a Flussonic Streamer API v3, então as integrações existentes continuam funcionando.

Acesso

O acesso à API é protegido por um login e uma senha na seção api_auth:

api_auth:
  login: admin
  password: secret

Endpoints

O prefixo base é /streamer/api/v3:

Método e caminho O que retorna
GET /streamer/api/v3/streams lista de streams e seu estado
GET /streamer/api/v3/config configuração atual do servidor
GET /streamer/api/v3/dvrs lista de armazenamentos DVR
GET /streamer/api/v3/dvrs/{name} estado de um DVR específico
GET /streamer/api/v3/rproxy estado do gateway Peeklio e dos agentes
GET /streamer/api/v3/monitoring/readiness sonda de readiness para orquestradores

API nativa v4

A API nativa, ainda em evolução, vive sob o prefixo /streamer/api-v4:

Caminho O que retorna
GET /listeners lista de listeners
GET /streams, GET /streams/{name} streams e seu estado
GET /streams/stats, GET /streams-stats estatísticas de streams
GET /sessions/stats estatísticas de sessões
GET /live-metrics, GET /sessions-metrics métricas de live e de sessões
GET /dvr, GET /dvr/catalog, GET /dvr/metrics estado do armazenamento e do catálogo DVR
POST /dvr/rebuild-index, GET (status), DELETE (parar) reconstrução do catálogo a partir dos discos
POST /dvr/cleanup, GET /dvr/cleanup iniciar a limpeza do arquivo / status
GET /runtime/metrics métricas do processo em formato Prometheus
GET /auth estado da autorização
GET /license/status estado da licença
GET /rproxy/streampoint-agents agentes do gateway Peeklio

Note

TODO: exemplos de respostas, gestão de streams pela API (quando surgirem operações de escrita).

O que vem a seguir

Acesso ao Admin API

O Admin API é protegido por uma seção separada api_auth — veja Admin API.

Saúde do servidor

  • Sonda de readiness: GET /streamer/api-v3/monitoring/readiness — para Kubernetes e balanceadores.
  • Estado dos streams: GET /streamer/api-v3/streams.

Estatísticas do stream na Admin API

A lista de streams

GET /streamer/api-v4/streams/stats traz um elemento por stream — a página de streams da UI vive dessa lista, e ela também é o certo para sondá-la de scripts.

Campo O que significa Como usar
status, status_since o estado do stream e o momento em que entrou nele fora de running por mais de N minutos — alerta
bitrate_kbit o bitrate de mídia medido da entrada ativa, pelos timestamps dos quadros despencou bem abaixo do nominal — a fonte se degradou. Isso não é o throughput de rede: um arquivo pode ser lido mais rápido que o tempo real
source.url a entrada que está tocando de fato difere da primeira do config — o stream vive numa reserva
inputs[] o status de runtime de cada entrada configurada: url, status, idade da verificação checked_ago_ms, bitrate, texto do erro veja abaixo
dvr.from, dvr.to a janela do arquivo neste servidor to fica atrás da hora atual — a gravação parou; from parou de avançar — a limpeza não funciona, transbordamento de disco à frente
dvr.recorded_hours, dvr.bytes, dvr.periods os totais do arquivo: quantas horas estão gravadas, quanto espaço em disco o arquivo ocupa e de quantos trechos contínuos ele consiste; atualizado uma vez por minuto, precisão de uma hora recorded_hours notavelmente abaixo da largura da janela to - from — o arquivo tem buracos; bytes — o espaço que o stream ocupa no servidor
bytes_in, bytes_out contadores cumulativos de bytes desde o início do stream para taxas e histórico use o servidor Prometheus embutido ou o Retroview: o retrato zera no restart

Status dos elementos de inputs[]:

  • active — tocando agora;
  • ok — uma reserva, viva na última verificação;
  • error — uma reserva com um problema registrado (texto em error);
  • unchecked — uma reserva que ainda nunca foi verificada.

Isso responde à principal pergunta do failover — «vamos comutar de verdade quando a principal morrer?». As reservas são verificadas periodicamente (recheck_secondary_inputs_interval, veja fontes reserva); alerte sobre error, sobre unchecked e sobre um checked_ago_ms velho demais — uma reserva não verificada não pode ser considerada operacional.

Um único stream

GET /streamer/api-v4/streams/stats/{name} acrescenta a esses mesmos campos seções de diagnóstico — elas ficam de fora da lista para que a lista continue barata.

A seção input — contadores da entrada atual:

Campo Para quê
bytes, frames, bitrate_kbit se a entrada traz dados e a que velocidade
retries reconexões à fonte: cresce — a fonte ou a rede está instável
input_switches comutações entre entradas: cresce — a entrada cai e volta; investigue a principal
errors o contador agregado de erros de entrada: cresce — há um problema; a causa está nos contadores estendidos ou no Retroview
num_sec_on_primary_input, num_sec_on_secondary_input segundos vividos na principal e na reserva: uma fatia notável na reserva — a entrada principal é sistematicamente ruim
num_sec_no_data segundos sem dados nenhum
errors_lost_packets, errors_connection_closed, errors_http_request_error, … detalhamento causal dos erros — somente com a opção de contadores estendidos

A seção dvr na resposta individual é ampliada com:

Campo Para quê
write.segments_written, write.segments_failed, write.segments_skipped contadores de escrita de fragmentos: segments_failed cresce — o arquivo está perdendo dados agora mesmo, verifique o disco
write.segments_written_slow / _delayed / _collapsed, write.segments_discontinuity perfilamento da escrita — somente com a opção de contadores estendidos

Note

O retrato da Admin API zera quando o servidor reinicia. Ele responde «o que está acontecendo agora», mas não serve nem para conciliar a conta nem para analisar o incidente de ontem — para isso existe o Retroview.