Observabilidade do cliente

Os SDKs do OpenTok oferecem métodos para acessar estatísticas de rede e de mídia em tempo real durante uma sessão de vídeo, incluindo estatísticas do lado do remetente.

A observabilidade do cliente fornece métricas detalhadas sobre a qualidade do fluxo — como perda de pacotes, dados recebidos e largura de banda estimada — e pode ser utilizada em qualquer fluxo publicado ou assinado.

É possível acessar as estatísticas por meio de dois mecanismos principais:

  • API de estatísticas de alto nível — o mecanismo preferido na maioria dos casos. Essa API fornece métricas de desempenho de áudio, vídeo e rede, além de levar em conta as transições entre conexões entre pares e outros ajustes internos. O SDK agrega esses detalhes para que os dados sejam mapeados de forma clara para uma abstração de editor ou assinante. Sempre que possível, use essa API, pois ela oferece uma representação mais precisa e estável do desempenho real da sessão.
  • Relatório de estatísticas de baixo nível do WebRTC, que expõe o RTCStatsReport bruto do WebRTC para a conexão entre pares subjacente. Esses dados não são ajustados para transições na conexão entre pares nem para otimizações internas e refletem apenas as estatísticas diretas do WebRTC. É útil para depuração avançada ou quando os dados brutos do WebRTC são explicitamente necessários.

Este guia inclui as seguintes seções:

A API de estatísticas de áudio e vídeo fornece informações periódicas e detalhadas sobre o desempenho de mídia, tanto para editores quanto para assinantes. Essas estatísticas permitem que as aplicações monitorem a qualidade de áudio e vídeo em tempo real, compreendam o comportamento da rede, detectem problemas no lado do dispositivo e respondam de forma proativa a mudanças na largura de banda ou no desempenho. A Video API está disponível em todos os SDKs do Video Client e oferece callbacks ou eventos separados para métricas do lado do editor e do lado do assinante.

Os principais tipos de dados e eventos fornecidos incluem:

  • Estatísticas de áudio e vídeo – tais como taxas de quadros, resolução, taxa de bits e contagem de pacotes, fornecidos periodicamente por meio de callbacks ou eventos.

  • Estatísticas de links de mídia – fornecem métricas unificadas no nível de transporte que complementam as estatísticas periódicas de áudio e vídeo, incluindo avaliação das condições da rede e estimativa de largura de banda. Para os assinantes, essas métricas oferecem, além disso, visibilidade sobre o desempenho de transporte do provedor remoto e a atribuição de degradação da rede, permitindo que as Applications diagnostiquem problemas de conexão com precisão e forneçam feedback significativo e prático aos usuários.

  • Eventos de alteração na qualidade do vídeo – acionado sempre que a qualidade de um fluxo de vídeo muda, fornecendo métricas atualizadas juntamente com o motivo de qualquer deterioração ou melhora.

  • Eventos de alteração nas condições da rede – acionados quando é detectada uma alteração significativa nas condições da rede para um emissor ou assinante. Esses eventos relatam mudanças no estado geral da rede e incluem um panorama completo das estatísticas de áudio e vídeo, juntamente com métricas no nível de transporte, como a pontuação das condições da rede e o motivo dessa condição. Para os assinantes, eles também incluem a origem da degradação da rede. Consulte Condição da rede para mais detalhes.

Estatísticas da editora

Os callbacks do editor oferecem uma visão da qualidade da mídia que está sendo enviado para cada assinante (ou para o Vonage Video Media Router em sessões roteadas). Essas métricas ajudam a compreender as condições da rede de upstream, observar o desempenho da codificação e diagnosticar problemas como perda de pacotes ou quedas na taxa de bits.

Observação: Em sessões encaminhadas, as métricas do emissor podem não corresponder aos valores reais da mídia, pois o Vonage Video Media Router pode limitar a largura de banda para otimizar os recursos. Nesses casos, não se baseie nas métricas do lado do emissor até que pelo menos um assinante esteja conectado. Você pode ignorar os motivos de limitação de qualidade relacionados à largura de banda do emissor até que haja um assinante presente. Em sessões retransmitidas, nenhuma estatística é relatada até que pelo menos um assinante esteja conectado.

Observe que, quando o emissor está em uma sessão retransmitida, ele envia um fluxo de mídia separado para cada assinante. Por esse motivo, os eventos de estatísticas podem incluir vários objetos de estatísticas — um por assinante. Para cada objeto de estatísticas em uma sessão retransmitida, são incluídos dois campos de identificação:

  • ID da conexão: O ID exclusivo da conexão do assinante. Esse ID corresponde à propriedade “ID” do objeto de conexão fornecido no evento “conexão criada” para esse cliente.
  • ID do assinante: O ID exclusivo do objeto Assinante que está recebendo o fluxo deste editor. Esse ID corresponde à propriedade “ID” do assinante no aplicativo do cliente que está se inscrevendo.

Esses campos permitem determinar a qual assinante cada objeto de estatísticas pertence.

Em uma sessão roteada (usando o Vonage Video Media Router), há apenas um fluxo de mídia de saída; portanto, a matriz de estatísticas contém um único objeto, e tanto o ID da conexão quanto o ID do assinante estão indefinidos.

Métricas de áudio

  • Pacotes perdidos: Número total de pacotes de áudio que não chegaram ao assinante.
  • Pacotes enviados: Número total de pacotes de áudio transmitidos ao assinante ou ao roteador de mídia.
  • Bytes enviados: Tamanho acumulado de todos os dados de áudio enviados, incluindo a carga útil de áudio, cabeçalhos e preenchimento.
  • Nível de áudio: Nível de intensidade atual do sinal de áudio, normalizado entre 0 e 1.
  • Data e hora: Indica quando cada medição foi realizada.

As métricas de transporte do editor e de condições da rede estão disponíveis nas estatísticas do link de mídia do editor. Consulte Estatísticas de links de mídia para mais detalhes.

Métricas de vídeo

  • Pacotes perdidos: Número de pacotes de vídeo que não chegaram ao destino.
  • Pacotes enviados: Número total de pacotes de vídeo transmitidos ao assinante ou ao roteador de mídia.
  • Bytes enviados: Número total de bytes transmitidos ao assinante ou ao roteador de mídia, incluindo a carga útil de vídeo, cabeçalhos e preenchimento.
  • Data e hora: Indica o ponto inicial e o ponto atual da medição.
  • Camadas de vídeo: Informações por camada para transmissão simultânea ou codificação de vídeo escalável (SVC). Em uma configuração de transmissão simultânea, cada objeto corresponde a uma codificação de vídeo independente (por exemplo, fluxos de baixa, média e alta resolução enviados em paralelo). Para SVC (Codificação de Vídeo Escalável), o editor normalmente envia uma única codificação de vídeo, com escalabilidade (temporal, espacial ou ambas) codificada internamente e descrita por meio do campo de modo de escalabilidade. Isso inclui:
    • Largura do quadro codificado: Largura dos quadros de vídeo codificados para esta camada. Esse valor pode diferir da resolução de captura da câmera caso seja aplicado redimensionamento ou adaptação.
    • Altura do quadro codificado: Altura dos quadros de vídeo codificados para esta camada. Assim como na largura, o codificador pode reduzir a resolução dos quadros com base na largura de banda, na CPU ou na configuração da camada de transmissão simultânea/SVC.
    • Taxa de quadros de saída do codificador: Taxa de quadros real na qual os quadros de vídeo são codificados com sucesso. Ela pode diferir da taxa de quadros de captura da câmera (os quadros podem ser descartados antes da codificação) e da taxa de quadros efetivamente transmitida (os quadros codificados podem ser descartados antes do envio).
    • Taxa de bits (apenas carga útil de vídeo): Taxa de bits estimada da carga útil do vídeo codificado. Isso exclui a sobrecarga do RTP e pode variar de acordo com as decisões de controle de taxa do codificador.
    • Taxa de bits total (incluindo sobrecarga): Taxa de bits que inclui cabeçalhos RTP, preenchimento e outras sobrecargas de transporte. Isso reflete melhor o uso real da rede do que apenas a taxa de bits da carga útil.
    • Modo de escalabilidade: Indica a estrutura de escalabilidade espacial/temporal (por exemplo, “L3T3”).
    • Codec: O codec utilizado para codificar esta camada (por exemplo, VP8, VP9, H.264, AV1).
    • Motivo da limitação de qualidade: indica por que o codificador limitou a qualidade (largura de banda, CPU, outros). Ajuda a diagnosticar se a adaptação é causada por condições da rede ou por restrições do lado do dispositivo.

As estatísticas de links de mídia dos editores incluem:

  • Estatísticas de transporte: Estatísticas de tráfego local e de rede para o editor, incluindo:
    • Largura de banda disponível estimada da conexão de uplink.
    • Pontuação da condição da rede. Consulte Condição da rede para mais detalhes.
    • Motivo relacionado à condição da rede. Consulte Condição da rede para mais detalhes.

Essas métricas são fornecidas por meio de:

  • Evento de estatísticas de links de mídia: Um evento dedicado, acionado periodicamente para relatar estatísticas de links de mídia.
  • Evento de alteração no estado da rede: É acionado quando é detectada uma mudança significativa nas condições da rede, fornecendo as estatísticas atuais do link de mídia juntamente com o motivo da mudança.

As estatísticas de link de mídia do editor descrevem o próprio uplink do editor. As estatísticas de link de mídia do assinante, além disso, relatam o transporte do provedor remoto e a fonte de degradação da rede. Consulte [Condição da rede por provedor e assinante](#network_condition_by_publisher and_subscriber) para saber como as duas perspectivas se relacionam e como avaliar a experiência de um assinante específico.

Estatísticas de assinantes

As chamadas de retorno do assinante fornecem informações sobre a mídia que está sendo recebido e processados, ajudando as aplicações a detectar problemas de reprodução, avaliar o desempenho a jusante e tomar decisões adaptativas.

Métricas de áudio

  • Pacotes recebidos: Quantos pacotes de áudio foram recebidos com sucesso.
  • Pacotes perdidos: Quantos pacotes de áudio não foram recebidos com sucesso.
  • Bytes recebidos: Total de dados de áudio recebidos do editor ou do Media Router da Video API.
  • Nível de áudio: Volume do áudio do controle remoto.
  • Data e hora: Quando as métricas foram coletadas.
  • Estatísticas do lado do remetente: Estimativas de largura de banda informadas pelo remetente.

As métricas de transporte do assinante e de condição da rede, incluindo estatísticas de transporte do editor remoto e informações sobre a origem da degradação da rede, estão disponíveis por meio das estatísticas do link de mídia do assinante. Consulte Estatísticas de links de mídia para mais detalhes.

Métricas de vídeo

  • Pacotes recebidos: Quantos pacotes de vídeo foram recebidos com sucesso.
  • Pacotes perdidos: Quantos pacotes de vídeo não foram recebidos com sucesso.
  • Bytes recebidos: Total de dados de vídeo recebidos do editor ou do Video API Media Router.
  • Resolução decodificada: Largura e altura dos quadros após a decodificação.
  • Taxa de quadros decodificada: Taxa de quadros real produzida pelo decodificador. Esse valor pode diferir do número de quadros recebidos (alguns podem ser descartados antes da decodificação) e do número de quadros renderizados (alguns quadros decodificados podem não ser exibidos, dependendo das condições de renderização).
  • Taxa de bits: Taxa de transferência de mídia recebida, considerando apenas a carga útil de vídeo.
  • Taxa de bits total: Taxa de transferência de dados recebida, incluindo cabeçalhos e preenchimento.
  • Número de travamentos do vídeo: Número de travamentos de vídeo, conforme definido na API de Estatísticas do WebRTC freezeCount.
  • Duração total dos congelamentos do vídeo: Duração total dos congelamentos do vídeo.
  • Número de pausas no vídeo: Número de interrupções com duração superior a 5 segundos, incluindo pausas intencionais (como quando o editor desativa a trilha de vídeo) e casos em que o vídeo é desativado devido a um fallback de áudio por parte do editor ou do assinante.
  • Duração total das pausas no vídeo: Duração total das pausas no vídeo.
  • Codec: Codec atualmente em uso para o fluxo de vídeo.
  • Estatísticas do lado do remetente: Estimativas de largura de banda informadas pelo remetente.

As estatísticas de links de mídia dos assinantes incluem:

  • Estatísticas do transporte local: Estatísticas de transporte e de rede para a conexão de downlink do assinante, incluindo:

    • Largura de banda disponível estimada da conexão de downlink.
    • Pontuação da condição da rede. Consulte Condição da rede para mais detalhes.
    • Motivo relacionado à condição da rede. Consulte Condição da rede para mais detalhes.

  • Estatísticas de transporte do editor remoto: Estatísticas de transporte e rede para a conexão de uplink do editor remoto, com os mesmos campos das estatísticas de transporte locais. Essas estatísticas podem ser limitadas se as estatísticas do lado do remetente não estiverem ativadas.

  • Fonte da degradação da rede: Identifica qual lado da conexão é o principal responsável por qualquer degradação observada:

    • Nenhum: Não foi detectada nenhuma degradação na rede.
    • Local: A rede do assinante local é a principal causa.
    • Remoto: A rede do editor remoto é a causa principal.
    • Ambos ou não está claro: A origem da degradação não pode ser claramente atribuída a uma das partes.

As estatísticas de links de mídia dos assinantes são fornecidas por meio de:

  • Evento de estatísticas de links de mídia: Um evento dedicado, acionado periodicamente para relatar estatísticas de links de mídia.
  • Evento de alteração no estado da rede: É acionado quando é detectada uma mudança significativa nas condições da rede, fornecendo as estatísticas atuais do link de mídia juntamente com o motivo da mudança.

Eventos relacionados à alteração da qualidade do vídeo

O SDK fornece eventos relacionados a alterações na qualidade do vídeo para oferecer às aplicações informações detalhadas sobre o fluxo de vídeo de um emissor ou de um assinante. Esses eventos complementam as estatísticas periódicas de rede fornecidas para a observabilidade do cliente e permitem que as aplicações reajam tanto a métricas contínuas quanto a mudanças significativas na qualidade.

É possível associar um manipulador a um emissor ou a um assinante para acessar eventos de alteração de qualidade. Esses eventos fornecem métricas atualizadas, juntamente com o motivo de qualquer degradação ou melhoria. Esse mecanismo permite que seu aplicativo monitore o desempenho do vídeo e adapte a interface do usuário ou o comportamento de acordo com isso, independentemente de como as métricas são fornecidas internamente.

Os motivos por trás dos eventos de qualidade são acionados de acordo com uma ordem de prioridade definida. Por exemplo, uma limitação de qualidade causada pela largura de banda tem precedência sobre uma alteração na resolução. Se você precisar acompanhar todas as alterações nas métricas, verifique as estatísticas detalhadas incluídas em cada evento. Consulte a documentação de referência do SDK para obter todos os detalhes.

Para uma editora, os motivos são considerados na seguinte ordem de prioridade:

  1. Deterioração devido à limitação da largura de banda
  2. Deterioração devido à limitação da CPU
  3. Outras causas de deterioração da qualidade
  4. Alterações no codec
  5. Alterações na resolução ou na camada de vídeo

Para um assinante, os motivos são considerados na seguinte ordem de prioridade:

  1. Interrupção do vídeo
  2. Alterações no codec
  3. Alterações na resolução

Monitoramento da qualidade das chamadas

Além das APIs estatísticas principais, o SDK do OpenTok.js oferece recursos adicionais para monitorar e responder a alterações na qualidade das chamadas em tempo real. Esses recursos ajudam as Applications a otimizar o desempenho, adaptando-se às limitações dos dispositivos e às condições da rede.

Nota: Os recursos de monitoramento da qualidade das chamadas, incluindo o monitoramento do desempenho da CPU e o acompanhamento do Índice de Satisfação Média (MOS), estão disponíveis atualmente apenas no SDK do OpenTok.js para aplicativos da web.

Principais recursos

Monitoramento do desempenho da CPU - Detecte alterações na carga da CPU do dispositivo e adapte seu aplicativo de acordo com isso. As applications podem responder à sobrecarga da CPU desativando recursos que exigem muitos recursos computacionais ou reduzindo a qualidade do vídeo para manter a estabilidade da chamada.

Pontuação Média de Opinião (MOS) - Avalie a qualidade da experiência percebida pelos usuários em relação ao seu serviço utilizando a escala MOS, padrão do setor (1 a 5). O algoritmo MOS leva em consideração a perda de pacotes, a taxa de bits, a latência da rede e outros fatores que afetam a qualidade da mídia.

Otimização combinada - Desenvolva aplicativos robustos que respondam tanto às métricas de desempenho da CPU quanto às de qualidade da rede, ajustando dinamicamente a resolução de vídeo, as taxas de quadros e outros parâmetros para oferecer a melhor experiência possível ao usuário em diversas condições.

Testes prévios à chamada - Use o Teste da rede da Video API da Vonage biblioteca para avaliar se um cliente é capaz de suportar a transmissão de áudio e vídeo e estimar os índices MOS antes que os usuários entrem em uma sessão.

Para obter orientações detalhadas sobre implementação, exemplos de código e práticas recomendadas para o monitoramento da qualidade das chamadas em aplicativos da Web, consulte o Documentação do SDK do OpenTok.js.

Estatísticas do lado do remetente

Durante uma chamada, o provedor transmite um fluxo de mídia para um ou mais assinantes. A mídia pode ser retransmitida diretamente ou processada por meio do Roteador de mídia de vídeo da Vonage. Embora os assinantes possam verificar a taxa de bits da transmissão que recebem, eles geralmente não têm visibilidade da capacidade total de download. A API de Estatísticas do Lado do Remetente resolve essa limitação ao fornecer métricas que ajudam os assinantes a avaliar a largura de banda disponível para receber mídia e otimizar a qualidade da transmissão.

Um remetente pode ser um Editor ou o Roteador de mídia de vídeo da Vonage, dependendo se o fluxo de mídia ocorre ponto a ponto ou por meio do roteador de mídia. A API é chamada de “Estatísticas do lado do remetente” porque o remetente é a fonte das métricas relatadas, que são enviadas ao destinatário, que é o assinante.

A API fornece duas métricas principais por pacote (par de áudio-vídeo): a taxa de bits máxima que o remetente pode estimar e a estimativa atual da largura de banda. A taxa de bits máxima é um limite máximo para o que pode ser estimado devido a restrições da plataforma. A estimativa atual da largura de banda é a largura de banda de downlink estimada da capacidade do canal de conexão entre pares do WebRTC disponível para mídia, independentemente da taxa de bits do fluxo.

Por exemplo, um editor pode enviar um fluxo VGA usando menos de 1 Mbps, enquanto o Vonage Video Media Router, que fornece as estatísticas do lado do remetente, pode estimar a largura de banda atual em 8 Mbps, indicando capacidade adicional do canal. Essas informações podem ser utilizadas pelo aplicativo para ajustar os layouts de vídeo ou acionar ações baseadas em políticas, como o Vonage Quality on Demand (QoD).

Observe que sua interpretação difere quando um sessão de conexão com um único par é criada. Em uma sessão de conexão ponto a ponto, vários pacotes de áudio e vídeo compartilham a mesma conexão; portanto, a estimativa da largura de banda total deve ser calculada somando-se as estimativas individuais de cada pacote. Em outras palavras, a largura de banda total é compartilhada entre todos os assinantes na conexão ponto a ponto.

Ativação das estatísticas do remetente

Para habilitar as estatísticas do remetente, use o método correspondente no Client SDK para ativar o rastreamento dessas estatísticas no editor. Uma vez ativadas, as seguintes métricas serão incluídas nos eventos regulares de estatísticas de áudio e vídeo do assinante:

  • A taxa de bits máxima que pode ser estimada para a conexão.
  • A estimativa atual da largura de banda da conexão.

Casos de uso

  • Otimização dos layouts dos assinantes: Utilize a largura de banda estimada pela API do remetente, juntamente com as estatísticas de RTC do ponto de extremidade local, para exibir um número elevado de assinantes com boa qualidade de vídeo.

  • Modo de mídia adaptável: Um assinante pode usar as estatísticas do remetente para determinar se a largura de banda estimada do remetente excede um limite definido (por exemplo, 500 kbps) e, assim, decidir se deseja se inscrever no modo somente vídeo ou somente áudio.

  • Escalonamento de carga: Utilize as estatísticas do lado do remetente para verificar se um assinante é capaz de lidar de maneira ideal com um aumento na carga — como, por exemplo, a transição do compartilhamento de tela com baixa taxa de bits para um vídeo ao vivo com alta taxa de bits.

  • Avisos sobre limites: Utilize as estatísticas do lado do remetente para acionar alertas aos assinantes caso a largura de banda estimada de uma conexão do remetente caia abaixo de um limite predefinido.

  • Condições de acionamento do Quality on Demand (QoD): Utilize as estatísticas do lado do remetente para acionar uma ação quando a capacidade estimada da rede para um fluxo assinado ficar abaixo de um determinado limite na rede móvel.

Notas

  • Dependendo do SDK, as estatísticas do lado do remetente podem não estar disponíveis imediatamente na primeira vez em que forem solicitadas ou no primeiro evento de estatísticas após a assinatura, devido à latência da rede.
  • Se você criar uma única sessão de conexão ponto a ponto, a largura de banda da conexão entre pares é compartilhada entre todos os assinantes. A taxa de bits máxima representa a taxa de bits mais alta que a conexão entre pares pode estimar, enquanto a taxa de bits atual reflete a taxa de bits de cada pacote de áudio e vídeo. Todos os assinantes na conexão peer única compartilham essa taxa de bits máxima. Leve isso em consideração ao avaliar a largura de banda disponível do remetente. Por exemplo, uma taxa de bits atual de 2 Mbps pode indicar boa qualidade se vários assinantes compartilharem a mesma conexão peer única.

Problemas conhecidos

Em alguns casos, quando a sessão é retransmitida — ou em certas configurações de roteamento com apenas dois participantes — e o Editor usa o Firefox, as estatísticas do lado do remetente podem não estar disponíveis devido a limitações do navegador.

Condição da rede

A API de condição de rede oferece visibilidade em tempo real sobre o estado da conexão de rede, tanto para emissores quanto para assinantes. Ela apresenta uma pontuação de condição de rede que reflete a qualidade geral da conexão, o principal motivo por trás dessa pontuação e — para os assinantes — informações sobre qual lado da conexão está causando qualquer degradação observada.

As métricas de condição da rede estão incluídas nas estatísticas do link de mídia e são transmitidas por meio de dois canais:

  • Estatísticas periódicas: Os campos relativos às condições da rede estão incluídos nas estatísticas de ligação de mídia fornecidas por meio de eventos periódicos de estatísticas de ligação de mídia. Consulte Estatísticas de links de mídia para mais detalhes.
  • Eventos relacionados a alterações nas condições da rede: Um callback ou evento específico é acionado sempre que é detectada uma alteração significativa nas condições da rede. Esse evento é distinto dos eventos de ativação/desativação de vídeo ou de fallback de áudio, e relata alterações no estado da rede, em vez de alterações no estado da trilha de mídia. Os aplicativos podem usar esse evento para responder a problemas de rede, como atualizar indicadores da interface do usuário, registrar dados de telemetria ou acionar comportamentos adaptativos. O evento inclui as estatísticas atuais do link de mídia, juntamente com o motivo da alteração.

Pontuação da condição da rede

A condição da rede é uma pontuação que reflete o estado geral da conexão de rede para um determinado meio de transporte (local ou remoto). A pontuação é calculada a partir de métricas como perda de pacotes e largura de banda disponível estimada. Valores mais altos indicam melhores condições de rede.

Pontuação Descrição
Desconhecido Não foi possível determinar o estado da rede.
Excelente Condições de rede excelentes. A qualidade do vídeo é ótima e a largura de banda estimada é suficiente para suportar a taxa de bits máxima para a resolução atual.
Ótimo Boas condições de rede. Podem ocorrer pequenos problemas ou problemas temporários.
Feira Condições moderadas da rede. A qualidade do vídeo pode ser limitada pelo remetente.
Aviso Condições de rede insatisfatórias. A qualidade do vídeo é fortemente afetada, e um aviso de desativação do vídeo é exibido se o recurso de fallback de áudio estiver ativado.
Crítico Problemas graves de rede. Se o recurso de fallback de áudio estiver ativado, o SDK desativa o vídeo para preservar a estabilidade da chamada.

Observação: A pontuação de qualidade da rede é relativa à configuração atual da mídia e às demandas de largura de banda. Ela reflete o grau de adequação da rede aos requisitos ativos (por exemplo, resolução de vídeo, taxa de bits, taxa de quadros). Por exemplo, se o aplicativo estiver configurado para usar uma resolução baixa da câmera ou uma taxa de bits mais baixa, a rede pode ser classificada como excelente, pois a demanda de largura de banda é mínima. Resoluções ou taxas de bits mais altas exigirão maior capacidade de rede e podem resultar em pontuações de qualidade diferentes nas mesmas condições de rede.

Motivo relacionado à condição da rede

Cada pontuação de condição da rede é acompanhada por um motivo que indica o principal fator que determinou a avaliação:

  • Nenhum: Não há motivo específico.
  • Largura de banda: A condição da rede é afetada pela largura de banda disponível.
  • Perda de pacotes: A condição da rede foi afetada pela perda de pacotes.

Fonte de degradação da rede

A fonte de degradação da rede identifica qual lado da conexão é o principal responsável por qualquer degradação observada na rede. Essa métrica está disponível para assinantes e fornece informações essenciais para determinar se os problemas de desempenho se originam do downlink do assinante ou do uplink do editor remoto.

A fonte de degradação da rede ajuda as aplicações a identificar a causa raiz dos problemas de rede, permitindo um diagnóstico direcionado e a comunicação com o usuário. Em vez de apenas informar que as condições da rede estão ruins, ela indica se o problema está na qualidade da conexão do assinante local ou na qualidade da conexão do editor remoto.

Valores possíveis:

  • Nenhum: Não foi detectada nenhuma degradação na rede. Tanto as conexões locais quanto as remotas estão funcionando bem.
  • Local: A rede local do assinante é a principal causa da degradação do serviço. Os problemas podem incluir sinal Wi-Fi fraco, alta perda de pacotes no downlink ou largura de banda disponível limitada na conexão do assinante.
  • Remoto: A rede do emissor remoto é a principal causa da degradação. O emissor está enfrentando condições de rede insatisfatórias em seu uplink, o que afeta a qualidade da transmissão recebida por este assinante.
  • Ambos ou não está claro: A degradação está ocorrendo em ambos os lados da conexão, ou não é possível atribuir claramente a origem a um dos lados. Isso geralmente ocorre quando tanto o assinante quanto o provedor estão enfrentando problemas de rede simultaneamente.

Condição da rede por provedor e assinante

Um emissor pode atender a muitos assinantes, enquanto cada assinante recebe um único fluxo de um único emissor. O relatório sobre as condições da rede segue este padrão: um emissor relata a condição de seu próprio uplink, e um assinante relata seu downlink, o uplink do emissor remoto e qual das partes é responsável por qualquer degradação.

Uma editora informa o link de sua propriedade. Em uma sessão roteada, o emissor mantém apenas uma conexão entre pares com o Roteador de mídia de vídeo da Vonage, independentemente do número de assinantes que recebem a transmissão. O Media Router encerra essa conexão e encaminha a mídia para cada assinante por meio de conexões separadas de sua responsabilidade. As métricas de transporte do editor, portanto, descrevem o segmento do caminho de mídia entre o editor e o Media Router — o segmento que o editor pode influenciar diretamente por meio de sua própria codificação e controle de taxa. É também por isso que a matriz de estatísticas de um editor roteado contém um único objeto com o ID da conexão e o ID do assinante indefinidos, conforme descrito em Estatísticas da editora. Em sessões com mais de dois participantes, estender essas métricas a todos os assinantes receptores não seria viável em grande escala e teria valor diagnóstico limitado: o Media Router encaminha o fluxo para um número indeterminado de assinantes; portanto, os dados do lado do editor não poderiam nem isolar um problema de rede nem atribuir uma falha a um participante específico.

A comunicação do link local mantém as transições do AMR transparentes. Embora Roteamento Adaptativo de Mídia (AMR) Embora lide especificamente com chamadas entre dois participantes, nas quais cada emissor tem um único receptor, um caminho de mídia retransmitido ainda pode migrar para o Media Router no meio da chamada quando participantes adicionais se juntam ou quando determinados recursos são ativados. Como as estatísticas do link de mídia do emissor descrevem o próprio link de rede do emissor — seu uplink, independentemente de esse link terminar em um assinante ou no Media Router —, seu significado e formato permanecem inalterados durante essa transição. Os aplicativos podem utilizar as estatísticas do emissor de maneira consistente, sem precisar rastrear a topologia atual ou se adaptar a ela no meio da chamada. Isso segue o objetivo de projeto estabelecido no início deste guia, em que a API de estatísticas de alto nível se mapeia claramente às abstrações do emissor e do assinante e permanece estável durante as transições.

Para chamadas com dois participantes, considere a perspectiva do assinante. Quando cada participante publica um fluxo e se inscreve em um fluxo, as estatísticas dos assinantes são suficientes para analisar ambas as direções. Se um assinante relatar uma fonte de degradação de Remote, o uplink do participante remoto está limitado — e é provável que o próprio assinante desse participante também esteja enfrentando condições prejudicadas, uma vez que as causas comuns (sinal Wi-Fi fraco, rede de acesso congestionada, cobertura de celular insatisfatória) afetam ambas as direções de um link. Considere isso como uma inferência, e não como uma garantia.

Veja também Correlacione as métricas do editor e do assinante para diagnosticar a causa raiz.

Relação com o recurso alternativo de áudio

O relatório sobre a condição da rede está alinhado com o mecanismo de fallback de áudio. Quando eventos de fallback de áudio são acionados nos níveis de aviso ou crítico, a condição da rede relatada reflete a mesma gravidade. A condição da rede indica o estado correspondente de aviso ou crítico para o editor, o assinante ou ambos, garantindo uma sinalização consistente entre as APIs de rede e de fallback de mídia.

O contrário também pode ocorrer: o estado da rede pode indicar um nível de aviso ou crítico sem que o recurso de fallback de áudio seja acionado, o que acontece quando esse recurso está desativado.

Ativação da condição de rede

A geração de relatórios sobre o estado da rede depende da combinação de vários recursos. Quanto mais recursos você ativar, mais detalhados e precisos serão os dados sobre o estado da rede:

  • Estatísticas do lado do remetente: Ative as estatísticas do lado do remetente no editor para permitir que os assinantes recebam métricas de transporte do editor remoto e uma atribuição mais precisa da origem da degradação da rede.
  • Opção alternativa de áudio do editor: Ative o recurso de fallback de áudio no editor para melhorar a precisão da avaliação das condições de rede no lado do editor.
  • Solução alternativa de áudio para assinantes: Ative o recurso de fallback de áudio no assinante para melhorar a precisão da avaliação das condições da rede do lado do assinante.

Sem esses recursos ativados, alguns dados sobre as condições da rede podem estar limitados ou indisponíveis.

Para receber eventos de alteração nas condições da rede, registre um callback ou um ouvinte para essas alterações no editor ou no assinante. O evento inclui as estatísticas atuais do link de mídia, contendo métricas sobre as condições da rede e do transporte. Para obter mais detalhes, consulte o guia do desenvolvedor de cada Client SDK na Ativação da coleta de estatísticas de áudio e vídeo seção.

Utilizando os insights de observabilidade do cliente

Esta seção oferece orientações práticas sobre como utilizar esses sinais de maneira eficaz e sobre os erros comuns que devem ser evitados.

Melhores práticas

Deixe o SDK ajustar a qualidade automaticamente e, em seguida, tome as medidas necessárias com base no resultado

O SDK já lida com a adaptação de qualidade automaticamente:

  • Do lado da editora: Quando a largura de banda ou a CPU estão limitadas, o editor reduz automaticamente a resolução e a taxa de quadros. Em configurações de transmissão simultânea ou SVC, isso significa que o codificador pode passar para uma camada espacial ou temporal inferior.
  • SFU (sessões roteadas): O Vonage Video Media Router seleciona a camada de transmissão simultânea adequada para cada assinante com base na largura de banda de downlink disponível desse assinante. Um assinante com conexão fraca receberá uma camada de resolução mais baixa sem qualquer intervenção do aplicativo.
  • Sessões transmitidas: O provedor reduz a resolução diretamente para cada usuário, já que envia transmissões individuais para cada assinante.

Você não precisa, nem deve, tentar reproduzir essa lógica em seu aplicativo. Em vez disso, use os eventos de observabilidade para react dependendo do resultado: atualize sua interface do usuário, registre dados de telemetria ou acione decisões de política de nível superior com base no que o SDK já relatou.

Se você observar um quality_limitation_reason de bandwidth nas métricas de vídeo do editor, o codificador já está limitando a saída. Use esse sinal para orientar as decisões relacionadas à experiência do usuário (como ocultar uma pré-visualização em alta resolução), em vez de aplicar substituições redundantes de resolução. Da mesma forma, se o motivo for cpu, considere liberar recursos da CPU em outras partes do seu aplicativo — por exemplo, pausando animações não essenciais, adiando o processamento em segundo plano ou reduzindo a complexidade da renderização da interface do usuário — para dar mais margem ao codificador.

Exibir um indicador de qualidade da rede em tempo real

Use a pontuação das condições da rede, obtida a partir das estatísticas do Media Link, para exibir um indicador de qualidade na sua interface do usuário — por exemplo, barras de intensidade de sinal ou um ícone colorido. Atualize o indicador somente quando as condições da rede mudanças (utilizando o evento de alteração da condição da rede) em vez de a cada atualização periódica das estatísticas. Isso evita atualizações desnecessárias da visualização, mantendo o indicador sensível a mudanças significativas na qualidade.

Para os assinantes, a fonte de degradação da rede informa que de que lado da chamada é afetada. Destaque isso na sua interface de usuário para que os participantes recebam um feedback específico e prático — por exemplo, “Sua conexão está instável” em vez de “O participante remoto está enfrentando problemas de rede” — em vez de um aviso genérico sobre a qualidade.

Use eventos para uma experiência do usuário adaptativa, em vez de sondagens

É preferível utilizar callbacks acionados por eventos em vez de verificar matrizes de estatísticas periódicas para a lógica de limites. Os eventos “mudança na condição da rede” e “mudança na qualidade do vídeo” foram criados especificamente para detectar transições significativas. Verificar as estatísticas periódicas a cada tick em busca de ultrapassagens de limites gera sobrecarga na CPU.

Quando for necessário agir com base em estatísticas periódicas, aplique um filtro anti-rebote à sua lógica ao longo de várias amostras consecutivas antes de acionar qualquer alteração na experiência do usuário.

Utilizar as estatísticas de transporte para tomar decisões sobre layout e políticas

As estatísticas de link de mídia do assinante apresentam métricas de transporte a partir de duas perspectivas simultaneamente:

  • Estatísticas do transporte local refletem a largura de banda que o remetente (o editor ou o Vonage Video Media Router) estima estar disponível para a conexão com este assinante. Como a estimativa de largura de banda no WebRTC é realizada pelo remetente com base no feedback do RTCP, esse valor representa a percepção do remetente quanto à capacidade do canal — e não uma medição feita pelo próprio assinante.
  • Estatísticas de transporte de editores remotos refletem as métricas de transporte de uplink do próprio provedor, conforme relatadas pelo próprio provedor.

Juntas, essas duas visualizações permitem que você analise todo o caminho entre o editor e o assinante. Use-as para tomar decisões proativas sobre layout e políticas:

  • Limitar o número de blocos de vídeo visíveis em um layout em grade, quando a capacidade estimada é baixa, ocultando os participantes com menor prioridade em vez de exibir vídeo congelado ou com qualidade reduzida.
  • Aplicar políticas de Qualidade sob Demanda (QoD) em redes móveis, quando a estimativa da largura de banda de transporte local fica abaixo de um limite definido, por exemplo, ao mudar de transmissões em alta definição para transmissões em definição padrão.
  • Exibir um aviso de capacidade antes de adicionar um novo fluxo de alta taxa de bits (como o compartilhamento de tela) a uma sessão, quando a estimativa da largura de banda de transporte local já estiver limitada.

Em uma rede com vários participantes, é possível ampliar essa abordagem utilizando estatísticas de transporte e sinais de limitação da CPU para distribuir um orçamento de qualidade entre os editores. O SDK adapta cada fluxo de forma independente e não tem conhecimento de quais participantes são importantes no seu layout — essa priorização é uma decisão tomada no nível do aplicativo. Use setPreferredResolution e setPreferredFrameRate Cabe ao desenvolvedor implementar isso: atribuir ao bloco em destaque o limite máximo de resolução e restringir os participantes em segundo plano a valores mais baixos. Quando o locutor ativo mudar ou as condições se alterarem, reequilibre os limites de acordo com a nova situação. Isso complementa a adaptação automática do SDK, que continua a operar dentro do limite definido pelo aplicativo.

Correlacione as métricas do editor e do assinante para diagnosticar a causa raiz

Os problemas de rede podem ter origem em qualquer um dos lados da chamada. Utilize a combinação das estatísticas do link de mídia do emissor e das estatísticas do link de mídia do receptor — juntamente com a origem da degradação da rede — para identificar a causa raiz:

  • Um aviso ou uma condição crítica na rede no uplink do editor, combinada com um Remote A origem da degradação nos pontos dos assinantes aponta para um problema na rede do provedor.
  • Uma redução na largura de banda disponível no canal de download do assinante, combinada com uma Local A origem da degradação está na própria conexão do assinante.
  • Quando ambos os lados apresentam degradação ou a fonte é Both or unclear, encare o problema como uma questão comum.

Estatísticas de log para análise pós-chamada e depuração

Armazene estatísticas periódicas e eventos relacionados a mudanças nas condições da rede em um pipeline de análise de back-end. As principais métricas que vale a pena registrar incluem:

  • Pontuação da condição da rede e motivo ao longo do tempo, por provedor e assinante.
  • Motivo da limitação da qualidade do vídeo e camada ativa (transmissão simultânea/SVC).
  • Largura de banda disponível estimada com base nas estatísticas do link de mídia.
  • Número e duração total dos travamentos e pausas do vídeo.
  • Pontuação MOS (SDK da web) como indicador da qualidade percebida da chamada.

A análise pós-chamada desses registros pode revelar padrões, como degradação recorrente em horários específicos do dia, em determinados tipos de rede ou em modelos específicos de dispositivos, orientando melhorias na infraestrutura e na experiência do usuário.

Antipadrões

Não substitua a adaptação automática de qualidade do SDK

O SDK já reduz a resolução e a taxa de quadros quando há restrições de largura de banda ou de CPU. Definir alterações manuais de resolução em resposta a cada evento de estatísticas geralmente entra em conflito com o controle de taxa do codificador e pode causar oscilação — alternância rápida entre níveis de qualidade —, o que prejudica a qualidade percebida mais do que uma redução automática e suave faria.

Se você tiver requisitos específicos de qualidade (por exemplo, uma resolução máxima permitida), configure-os de forma declarativa na configuração da sessão, em vez de reagir a eventos de estatísticas durante a execução.

Não acione manualmente o recurso de fallback apenas de áudio com base nas estatísticas de transporte

Os SDKs opção alternativa de áudio Esse recurso já monitora as condições da rede e desativa automaticamente o vídeo quando a conexão se deteriora para um nível de alerta ou crítico. Implementar sua própria lógica para mudar um assinante para o modo somente áudio com base na estimativa de largura de banda de transporte local duplica esse comportamento integrado e pode entrar em conflito com ele — por exemplo, desativando o vídeo prematuramente antes que os próprios limites do SDK sejam atingidos, ou reativando-o em um momento diferente do que o SDK faria. Se você precisar de um comportamento de fallback de áudio, use o recurso de fallback de áudio do SDK em vez de controlá-lo diretamente a partir das estatísticas de transporte.

Não acione alterações na interface do usuário a cada evento de estatísticas periódicas

As métricas periódicas são geradas em intervalos regulares (normalmente a cada poucos segundos). Aplicar atualizações na interface do usuário ou lógica de negócios a cada evento, especialmente verificações de limite em métricas instáveis, como perda instantânea de pacotes, resulta em indicadores instáveis e alertas espúrios. Sempre suavize seus sinais: exija várias amostras consecutivas abaixo de um limite ou use o evento dedicado à mudança de condição de rede antes de atualizar o estado visível ao usuário.

Não se baseie apenas nas métricas do lado do editor para avaliar a experiência do assinante

As métricas do emissor refletem a qualidade da transmissão no sentido ascendente. Um emissor pode indicar excelentes condições de rede, enquanto um ou mais assinantes enfrentam baixa qualidade no sentido descendente. Para avaliar a experiência de um assinante específico, combine sempre as estatísticas do link de mídia do emissor com as métricas do lado do assinante, incluindo a origem da degradação da rede.

Não utilize contagens brutas de bytes ou pacotes como indicadores de qualidade

Totais acumulados como bytesReceived ou packetsLost crescem de forma monótona e não têm significado inerente por si só. Sempre calcule as taxas (delta no intervalo entre amostras) ou utilize os campos de nível superior, como a taxa de bits estimada ou a pontuação da condição da rede, que o SDK já calcula a partir dos contadores brutos.

Não utilize métricas de RTC de baixo nível para a medição da qualidade de ponta a ponta

O relatório de estatísticas do RTC reflete a situação de um único conexão entre pares subjacente em um determinado momento. O SDK pode migrar entre conexões entre pares ou mudar de topologia durante uma sessão; portanto, as estatísticas brutas do RTC não são agregadas ao longo dessas transições. Para medição de qualidade de ponta a ponta e monitoramento de sessões de longa duração, sempre dê preferência às APIs de alto nível para estatísticas de áudio, vídeo e links de mídia, que levam em conta essas mudanças internas.

Não ignore as diferenças entre sessões roteadas e retransmitidas

Em uma sessão roteada, as estatísticas do lado do remetente são fornecidas pelo Vonage Video Media Router, e as estimativas de largura de banda do lado do assinante refletem o downlink do assinante para o roteador de mídia — e não uma medição direta do uplink do emissor. Em uma sessão retransmitida (ponto a ponto), o editor envia fluxos individuais para cada assinante, e as estatísticas do editor representam medições diretas entre pares. Ao criar análises ou lógica adaptativa, leve em consideração o modo da sessão para evitar interpretações errôneas dos números.

Relatório de estatísticas da RTC

A Reports API do RTC fornece acesso a estatísticas WebRTC padronizadas de baixo nível para o fluxo de mídia publicado e assinado. Isso permite que as aplicações recuperem métricas detalhadas no formato definido pela especificação WebRTC, possibilitando monitoramento e análise avançados, além das métricas personalizadas de observabilidade do cliente.

Observação: Esta API fornece estatísticas de baixo nível sobre conexões entre pares. O SDK de vídeo pode otimizar conexões entre pares, fazer a transição entre diferentes topologias ou migrar para outro servidor de back-end. Essas estatísticas de baixo nível não agregam as métricas das diferentes conexões entre pares em uso ou das quais ocorreu a transição. Portanto, é preferível utilizar nossa API de estatísticas de áudio e vídeo para o monitoramento de ponta a ponta.

Ativação da coleta de estatísticas de áudio e vídeo

No publisher ou no subscriber, monitore os eventos de estatísticas correspondentes. Para obter mais detalhes, consulte o guia do desenvolvedor correspondente a cada Client SDK: