Estatísticas¶

O Sapsan sempre coleta o conjunto completo de contadores — a licença e a tarefa só determinam por qual canal você os lê. São quatro canais:

A regra de escolha é simples:

• «O que está acontecendo agora?» — a Admin API ou a UI.
• «O que aconteceu nas últimas horas?» — o servidor Prometheus embutido.
• «O que aconteceu na semana passada e por que caiu de madrugada?» — Retroview.
• «Quero meu próprio Prometheus, Grafana e alertmanager» — a opção de contadores estendidos.

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.

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:

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

Estatísticas de pushes¶

A entrega de saída é contada à parte da captura e por push: a chave da estatística é o par «nome do stream, nome do push», o mesmo da configuração. Um stream pode sair para cinco destinatários, e «o stream envia 40 Mbit/s» não responde se ele chega a algum deles em particular.

A seção pushes¶

GET /streamer/api-v4/streams/stats/{name} (e cada item de GET /streamer/api-v4/streams/stats) traz um objeto indexado pelo nome do push:

"pushes": {
  "cdn-main": {
    "status": "running",
    "proto": "udp",
    "url": "udp://127.0.0.1:5500",
    "opened_at": "2026-08-13T11:17:53Z",
    "bitrate_kbit": 2113.4,
    "bytes_total": 19053048,
    "datagrams_total": 14478
  },
  "youtube": {
    "status": "error",
    "proto": "rtmp",
    "url": "rtmp://198.51.100.7/live/secret-key",
    "error": "rtmp connect failed: timeout after 5s",
    "reconnects_total": 22
  },
  "backup-dc": {"status": "disabled", "proto": "srt", "url": "srt://203.0.113.10:9000"}
}

Campos zerados são omitidos da resposta: um push RTMP não tem datagramas, um UDP não tem quadros nem retransmissões.

Ao lado dos contadores do stream, como campos de nível superior da mesma resposta, há três somas sobre todos os pushes — push_bytes_total, push_errors_total, push_reconnects_total. Elas respondem «quanto o stream enviou no total» sem percorrer o mapa.

Séries do Prometheus¶

Cada contador de push é uma série própria com o rótulo push:

No servidor Prometheus embutido os mesmos contadores estão disponíveis com os rótulos name (o stream) e push; no central soma-se node a eles. A profundidade de protocolo — stream_push_srt_* e stream_push_rist_* — chega no scrape do nó junto com a opção de contadores estendidos.

# velocidade de envio por destino
rate(stream_push_bytes_total{stream="tv1"}[1m])

# a saída total do stream por todos os pushes
sum by (name) (rate(stream_push_bytes_total{name="tv1"}[1m]))

# canais que rompem: reconexões em cinco minutos
increase(stream_push_reconnects_total[5m]) > 0

# perdas no caminho até o receptor por SRT/RIST
rate(stream_push_retransmitted_packets_total[1m])

Como ler o estado¶

• status: error com error não vazio — nada está sendo enviado, e a causa está nomeada. O push continua se levantando sozinho, uma vez a cada cinco segundos.
• status: running, mas bitrate_kbit zerado — a conexão está lá, os dados não: confira se o próprio stream está rodando.
• status: running com reconnects_total crescente — o canal rompe e se recupera; olhe opened_at, ele mostra a idade da conexão atual.
• status: disabled — o push está desligado na configuração. Seus contadores ficam congelados nos últimos valores; nada é perdido.

O servidor Prometheus embutido¶

O Sapsan contém um servidor Prometheus embutido: a HTTP API /api/v1/query, /api/v1/query_range, /api/v1/series, /api/v1/labels, /api/v1/label/{name}/values, /api/v1/status/buildinfo sobre um armazenamento próprio em memória. Para o Grafana é um datasource pronto: adicione um datasource do tipo Prometheus, aponte para a URL do servidor — e construa gráficos sem implantar uma TSDB. Os gráficos da UI embutida se alimentam dessas mesmas consultas.

Limites de construção:

• o histórico é de algumas horas, em memória; depois de um restart o armazenamento fica vazio. É o canal do «o que está acontecendo agora», não um arquivo de métricas;
• o PromQL é suportado como um subconjunto: seletores com matchers de rótulos, rate/irate/increase, as agregações sum/avg/min/max/count com by()/without(), aritmética, offset. Uma construção não suportada devolve um erro explícito, não um resultado distorcido;
• o conjunto de séries é o básico; as séries profundas (por PID, SRT, RTP) aparecem com a opção de contadores estendidos.

Consultas a um único servidor¶

# velocidade de captura do stream, bytes/s
rate(stream_input_bytes_total{stream="cam1"}[1m])

# erros de entrada nos últimos 5 minutos
increase(stream_input_errors_total{stream="cam1"}[5m])

# o arquivo está sendo escrito com erros?
increase(stream_dvr_write_segments_failed_total{stream="cam1"}[10m])

# tráfego total de captura do servidor
sum(rate(stream_input_bytes_total[1m]))

# memória usada pelos streams, por parte do pipeline
sum by (part) (stream_memory_bytes)

Num servidor único as séries não carregam o rótulo node.

Consultas ao central¶

O central e os nós Sapsan formam um único complexo: o central coleta as estatísticas de todos os nós, e o servidor Prometheus embutido dele serve exatamente o mesmo API. Há uma única diferença, mas ela atravessa tudo — o rótulo node:

• cada série carrega node="nome-do-nó" — dá para ver qual nó a produziu;
• um stream pode dar várias séries: um stream de cluster é servido em partes em nós diferentes;
• node aparece em /api/v1/labels e em label_values(node) — é disso que se faz uma variável de dashboard do Grafana com um menu suspenso de nós.

# o stream inteiro, não importa em quantos nós ele vive
sum without (node) (rate(stream_input_bytes_total{stream="cam1"}[1m]))

# tráfego de captura do complexo, detalhado por nós
sum by (node) (rate(stream_input_bytes_total[1m]))

# em quais nós o stream vive agora — olhe o rótulo node do resultado
stream_input_bytes_total{stream="cam1"}

O mesmo dashboard funciona tanto contra um Sapsan único quanto contra o central: agregue com sum without (node) — num servidor único o rótulo não existe, e a agregação não muda nada.

O scrape do Prometheus: o seu próprio monitoramento¶

Para instalações com infraestrutura de monitoramento própria, o Sapsan serve métricas no formato de texto do Prometheus:

• GET /streamer/api-v4/live-metrics — streams e entradas;
• GET /streamer/api-v4/sessions-metrics — sessões de reprodução;
• GET /streamer/api-v4/dvr/metrics — discos e catálogo do arquivo;
• GET /streamer/api-v4/runtime/metrics — o processo e o alocador.

Diferenças em relação ao servidor Prometheus embutido: o histórico fica guardado do seu lado e é limitado só pelo retention da sua TSDB; a profundidade completa está disponível, incluindo as métricas de protocolo por PID/SRT/RTP; o alerting é o seu alertmanager. Os contadores são monótonos e sobrevivem à observação de restarts — este é também o canal para a conciliação de faturamento do seu lado.

Contadores estendidos¶

A opção de contadores estendidos abre o detalhamento causal e de protocolo em todo lugar ao mesmo tempo: nas seções input e dvr.write da Admin API, nas séries do servidor Prometheus embutido e no scrape do Prometheus. Na telemetria do Retroview esses contadores sempre vão, independentemente da opção — por isso a análise de causas está disponível no Retroview mesmo sem ela.

Causas dos erros de entrada¶

O errors agregado responde «há um problema na entrada»; o detalhamento causal responde «qual exatamente». As causas vêm em duas famílias:

• defeitos de mídia de um stream vivo — lost_packets, broken_payload, desync, ts_pat: os dados chegam, mas danificados;
• falhas da fonte — connection_closed, connection_refused, timeout, http_request_error, not_found, denied, decode_error, protocol_error, io_error, other: a fonte morreu, e a causa da morte está classificada.

A classificação vem da categoria tipada do erro, e não do texto do log, e cobre inclusive a falha ao abrir uma fonte. Cada falha entra também no errors agregado; as falhas repetidas nas tentativas são contadas a cada vez — a frequência de eventos é exatamente o sinal de «a fonte ainda está morta». As paradas normais — reconfiguração, fim do stream, desalojo por uma fonte de maior prioridade — não contam como erros.

A série do detalhamento¶

No servidor Prometheus embutido o detalhamento viaja como uma série com o rótulo de causa — errors_detail_total{name, cause}; no central as séries levam também node. Causas sem eventos não criam séries.

# erros do stream em 5 minutos, detalhados por causa
sum by (cause) (increase(errors_detail_total{name="tv1"}[5m]))

MPEG-TS por cada PID¶

Por cada PID do fluxo de transporte: errors_ts_cc (violações de continuity counter — o principal indicador de perdas de transporte), errors_ts_tei, errors_ts_scrambled (a criptografia não foi retirada — problemas de CAM/chaves), errors_ts_psi_checksum, PES quebrados, buckets de jitter do PCR, esvaziamentos do buffer do decodificador (HRD).

Por quê: este é material de monitoramento de nível broadcast. Um alerta sobre rate(errors_ts_cc) > 0 por PID pega a degradação do transporte antes que o espectador a veja; o jitter do PCR e o HRD mostram se o stream sobreviverá a um decodificador de hardware.

SRT¶

RTT e sua variação, perdas e retransmissões nos dois sentidos, descartes por atraso, enchimento dos buffers, tempos limite de keepalive.

Por quê: ajustar a latency ao canal real e diagnosticar «quem perde — nós ou o lado remoto». As retransmissões crescem com o RTT estável — perdas no caminho; o RTT pula — o canal está congestionado.

RTP/RTSP por canal¶

Pacotes perdidos, saltos e travamentos dos timestamps, NACKs, transbordamentos de buffer — por cada canal RTP (vídeo/áudio) de uma câmera.

Por quê: diagnóstico do parque de câmeras — qual câmera está falhando, antes de chegarem as reclamações de artefatos.

Desempenho de escrita do DVR¶

segments_written_slow, segments_written_delayed, segments_written_collapsed, segments_discontinuity.

Por quê: um sinal precoce de «o disco não dá conta». A fatia de slow/delayed cresce com o mesmo tráfego — o armazenamento está degradando; discontinuity significa buracos que você verá depois em recorded_hours.

Retroview¶

O Retroview é o monitoramento em nuvem do fabricante. Uma vez por minuto o Sapsan envia telemetria — o catálogo completo de contadores, incluindo todo o detalhamento estendido — e o Retroview o guarda por meses. No servidor não há nada para configurar: o canal funciona junto com a licença.

Quando ir ao Retroview, e não ao servidor Prometheus embutido:

• histórico e tendências — o crescimento do tráfego e do número de streams ao longo de meses, planejamento de capacidade;
• post-mortems — o que estava acontecendo com o stream de madrugada: a telemetria sobrevive a restarts e não depende da memória do servidor;
• conciliação de consumo — os contadores são amostrados no tempo por um sistema externo, então a conta pode ser conferida mesmo que os servidores tenham sido reiniciados;
• análise de causas sem a opção de contadores estendidos — a telemetria sempre carrega o detalhamento causal;
• alertas prontos — regras de produto em vez de regras caseiras.

Receitas¶