Sessões de visualização¶
media.play.sessions
Uma sessão de visualização é o estado que o Sapsan mantém para o acesso de um espectador a um stream. Ela vincula as requisições do reprodutor à autorização e registra a atividade, os bytes entregues e o uso do arquivo. Isso permite observar a visualização como um todo, mesmo quando a entrega consiste em muitas requisições HTTP separadas.
Por exemplo, um reprodutor HLS solicita uma playlist mestre, as qualidades e uma sequência de segmentos. A adaptação de qualidade e novas conexões HTTP não devem, por si só, transformar uma visualização em centenas de espectadores. O Sapsan encontra a sessão existente e associa a ela as requisições seguintes.
Como as requisições HTTP são agrupadas¶
Na reprodução HTTP comum, a identidade é formada pelos seguintes dados:
- Nome do stream — o recurso de mídia solicitado.
- Tipo de acesso — a reprodução é separada da publicação.
- Endereço IP do cliente — considerando os proxies confiáveis configurados.
- Token de acesso — para um bilhete JWT validado, usa-se o identificador da concessão
jti.
O Sapsan usa esses dados para procurar a sessão a cada requisição. Se já houver uma sessão correspondente, a requisição atualiza sua atividade. Caso contrário, uma nova sessão é criada e a admissão é verificada. Uma requisição de fragmento também pode iniciar uma sessão: obter a playlist mestre não é uma primeira etapa obrigatória.
O servidor atribui o identificador da sessão. Um cliente HTTP comum não precisa gerar seu próprio UUID de sessão nem manter um cookie especial. O User-Agent é registrado nas estatísticas, mas não faz parte da chave de agrupamento acima.
O token deve chegar às requisições relacionadas. Na reprodução HTTP, o parâmetro ?token= tem prioridade sobre Authorization: Bearer …. A emissão e a entrega de JWT são descritas em tokens de acesso.
Esse registro depende da identidade escolhida, não do dispositivo físico. Vários reprodutores com o mesmo IP, o mesmo token e o mesmo stream podem compartilhar uma sessão. Uma mudança de IP ou do identificador do token pode criar uma nova. Para contabilizá-los separadamente, emita bilhetes distintos e configure corretamente os proxies confiáveis.
Ciclo de vida e estatísticas¶
As requisições e os dados entregues mantêm a atividade da sessão. Após 60 segundos sem atividade, a sessão expira; a limpeza é periódica, portanto o encerramento não precisa coincidir com o fechamento da aba do navegador.
Um registro de sessão aberto e um espectador ativo são indicadores diferentes. A implementação atual ativa a sessão após entregar 10 KiB de dados. Assim, uma única requisição de uma playlist pequena não aumenta necessariamente o número de espectadores ativos. O limite mede bytes entregues e não confirma que uma pessoa assistiu à imagem. Somente sessões que ficaram ativas entram no registro de sessões encerradas.
As seguintes informações são registradas:
- Tempo — abertura, última atividade, duração e encerramento.
- Entrega — protocolo e quantidade de bytes entregues.
- Cliente — IP,
User-Agente identificador do usuário, se fornecido pela autorização. - Arquivo — um indicador de acesso ao DVR. Depois de retroceder para o arquivo, ele permanece marcado mesmo ao voltar à transmissão ao vivo.
A transição ao vivo → arquivo → ao vivo não cria, por si só, três visualizações. Da mesma forma, requisições de segmentos e conexões de rede não devem ser somadas como espectadores.
Qualidade de entrega SRT¶
Uma sessão aberta por SRT leva um corte protocolar da entrega — contadores atuais da conexão na resposta de sessões ativas:
| Campo | Significado |
|---|---|
rtt_ms, rtt_max_ms |
RTT atual e máximo durante a vida da sessão |
send_buffer_packets |
pacotes no buffer de envio — sinal precoce de congestionamento no espectador |
packets_sent |
pacotes enviados — o denominador da proporção de perdas |
lost_packets |
perdas: falhas na sequência de saída de pacotes |
drop_too_late_packets |
das perdas — pacotes saltados como vencidos: a latência não deu conta de os recuperar |
drop_requests |
das perdas — pacotes descartados por ordem do receptor: o espectador informou que já não precisa daquele intervalo |
retransmitted_packets |
pacotes reenviados — respostas aos relatórios NAK do espectador |
naks_received |
relatórios NAK do espectador: quantas vezes ele informou perdas |
health |
veredicto de saúde da conexão: ok, degraded ou bad |
Os valores de uma sessão ativa atualizam-se: o nó fixa periodicamente os contadores no registo da sessão. No encerramento, o registo do nó recebe os totais finais e o veredicto da última janela.
O veredicto health descreve a janela de entrega — o último minuto da conexão, não toda a sua vida: a proporção de perdas e o RTT atual frente ao dobro da latência de entrega. Falhas passadas ficam no passado: quando a janela fica limpa, o veredicto volta a ok, e o quando caía lê-se na história do corte (veja a história por minutos). Uma quebra de conexão não estraga o veredicto: uma sessão limpa encerrada por um espectador que silenciou conserva o veredicto da sua última janela, e a partida mesma é descrita pela razão de encerramento.
Sessões dos demais protocolos não levam seção srt de todo — a ausência do campo não significa perdas zero.
História por minutos da sessão¶
Sessões com proprietário user_id — do mapa de clientes da entrega ou da etiqueta de proprietário — são escritas no armazém de métricas do central em pontos por minutos: o gráfico de uma sessão é construído pelo mesmo mecanismo que os gráficos da entrada do stream. Cada série leva as etiquetas name (stream), user_id e session:
| Série | O que mostra |
|---|---|
stream_play_srt_session_rtt_seconds, ..._rtt_max_seconds |
RTT — atual e máximo |
stream_play_srt_session_send_buffer_packets |
buffer de envio, pacotes |
stream_play_srt_session_packets_sent_total, ..._bytes_total |
pacotes e bytes enviados |
stream_play_srt_session_lost_packets_total |
perdas |
stream_play_srt_session_drop_too_late_packets_total, ..._drop_requests_total |
perdas por causa: saltados como vencidos e descartados por ordem do receptor |
stream_play_srt_session_retransmitted_packets_total, ..._naks_received_total |
retransmissões e relatórios NAK |
As séries são lidas no servidor Prometheus integrado do central com a mesma consulta de intervalo que as séries do stream. A profundidade do detalhe é a janela do armazém, seis horas por defeito; um reinício do plano de métricas apaga a história. Mais fundo que a janela estão os totais gerais do registo encerrado — bytes, duração, razão de encerramento. Sessões anónimas não criam séries: sem proprietário não há gráficos, e não zeros.
Autorização da sessão¶
O principal método recomendado de admissão é um bilhete JWT. O streamer o valida localmente, enquanto o estado da sessão vincula as requisições e seu tráfego. Uma sessão já aberta não elimina a validação do JWT na próxima requisição HTTP.
Para integrações antigas com um backend de autorização externo, a permissão é mantida por um período definido. Dentro dessa janela, as requisições seguintes reutilizam a decisão; após a expiração, é necessária uma nova autorização. O auth_duration, cujo padrão é 180 segundos, corresponde à validade da decisão de autorização, não ao tempo limite de inatividade de 60 segundos.
Verificar as próximas requisições HTTP e encerrar uma resposta contínua já aberta são operações diferentes. A existência de uma sessão não significa que uma mudança na decisão de autorização interrompa imediatamente qualquer entrega MPEG-TS em andamento.
Diferença em relação à validação de links em um edge nginx¶
A validação de um link assinado determina se uma requisição específica é permitida. Por exemplo, o módulo secure_link do nginx verifica a autenticidade do link e sua validade. O registro da visualização exige um estado que relacione as requisições individuais do reprodutor.
| Tarefa | Apenas validação do link | Registro de sessões do Sapsan |
|---|---|---|
| Admitir uma requisição de segmento | Valida o link apresentado | Verifica o acesso e vincula a requisição a uma visualização. |
| Contabilizar uma visualização | Requisições individuais não definem, por si só, seus limites | Registra a atividade e o ciclo de vida da sessão. |
| Contabilizar o tráfego | Há dados de cada requisição | Os bytes são acumulados na sessão. |
| Analisar retrocesso e protocolo | Exige agregação adicional | Essas informações fazem parte do registro da sessão. |
| Reunir dados de vários edges | Exige um mecanismo comum de registro | O central reúne dados dos streamers e fornece um histórico do cluster. |
O nginx pode ser integrado a estado e análise externos. A comparação se refere a uma configuração em que o edge apenas valida links: essa verificação, por si só, não é um registro de sessões de visualização.
Sessão do cluster e mudança entre edges¶
Com balanceamento de carga, um espectador pode iniciar a reprodução no edge A e continuar no edge B. Para analisar essa visualização, o central reúne dados dos servidores, armazena sessões encerradas em um registro comum e produz um histórico com uma etapa de união dos registros.
No histórico do cluster, registros com a mesma identidade reconhecida são unidos quando seus intervalos se sobrepõem ou estão separados por no máximo 30 minutos. Os bytes entregues são somados, o período abrange o intervalo unido e nodes lista os servidores participantes. Isso fornece um modelo de visualização lógica sobre os registros individuais dos servidores.
A implementação atual tem uma limitação: a leitura do histórico depende, na prática, de valores completos de id coincidentes. Ao abrir a reprodução em outro edge, esse ID pode mudar porque inclui o horário de abertura. Portanto, a união de todas as mudanças entre edges ainda não é garantida. O identificador do bilhete JWT, por si só, não elimina essa limitação da saída atual do histórico.
A lista atual de sessões ativas e o histórico unido de sessões encerradas são visualizações diferentes dos dados. O número de linhas na lista ativa não indica automaticamente o número de pessoas únicas em um período nem o resultado da união histórica.
Consulta pela API¶
Sessões atuais do stream no central:
curl -fsS -u "$ADMIN_USER:$ADMIN_PASSWORD" \
'http://central:8080/central/api-v4/play-sessions/active?stream=cam1&limit=100'
Histórico com união dos registros:
curl -fsS -u "$ADMIN_USER:$ADMIN_PASSWORD" \
'http://central:8080/central/api-v4/play-sessions/closed?stream=cam1&limit=100'
A resposta contém um array sessions. Os campos id, bytes, duration e dvr descrevem a visualização; node e nodes, a participação dos streamers. O uncovered_nodes identifica servidores cuja coleta de dados está incompleta. Um servidor sem cobertura não deve ser tratado como um servidor com zero espectadores.
Para diagnóstico local, o streamer disponibiliza os caminhos correspondentes /streamer/api-v4/play-sessions/active e /streamer/api-v4/play-sessions/closed. A coleta de histórico no central é assíncrona: encerrar uma sessão localmente não significa que ela apareça imediatamente no registro comum.