Inspetor

Uma ferramenta de diagnóstico pós-chamada para suas sessões da Video API

Usar o Inspector

Observação: Clique aqui aqui para obter informações sobre retenção de dados e latência.

O Inspector é uma ferramenta que ajuda a entender o que aconteceu em um OpenTok específico sessões. Os usuários podem inserir um ID da sessão ou use o Painel da sessão para acessar as seguintes informações sobre uma sessão:

• Estatísticas gerais
• Dados do usuário
• Erros
• Qualidade de vídeo e áudio
• Eventos

O Inspector é utilizado principalmente para depuração de sessões problemáticas que ocorreram no seu aplicativo OpenTok. É necessário estar conectado à sua conta da Video API do Vonage para acessar o Inspector, e você só poderá visualizar as sessões criadas a partir de chaves de API associadas à sua conta.

Pesquisando sessões

Antes de se aprofundar nas informações detalhadas sobre uma sessão, você precisa primeiro localizar a sessão. A melhor maneira de fazer isso é registrar o ID de cada sessão criada em seu aplicativo, para facilitar a depuração. No entanto, se você não souber o ID da sessão, pode usar o Painel da sessão para visualizar as sessões ativas recentemente, bem como as sessões inspecionadas recentemente.

Guia do Inspetor

Depois de selecionar ou pesquisar uma sessão específica, você será direcionado para a visualização da sessão no Inspector, onde poderá visualizar os dados relativos a essa sessão.

Na parte superior do Inspector, selecione o fuso horário no qual deseja exibir os dados da sessão. O seletor de fuso horário está identificado como “Hora exibida em”, no lado direito do banner do Inspector, na parte superior da página.

A visualização da sessão está dividida em várias seções, descritas a seguir:

Resumo e Estatísticas

Na parte superior da tela, encontram-se as seções “Resumo” e “Estatísticas”. Essas seções oferecem uma visão geral de alto nível do que ocorreu em uma sessão. Esses dados podem ser úteis para compreender rapidamente a topologia, a duração e a diversidade da sessão. Também são úteis para Verify se você está analisando a sessão correta durante a depuração.

Em alguns casos, talvez você queira aprofundar a análise em aspectos específicos reuniões dentro de uma sessão maior — para isso, basta clicar no Seletor de Reuniões, no canto superior direito, e selecionar o segmento da reunião que você deseja visualizar. Nos casos em que uma sessão inclui várias reuniões distintas, isso pode ajudar a simplificar a visualização, facilitando a depuração.

O painel “Estatísticas das reuniões” inclui as seguintes informações:

• O tipo de chamada. Pode ser multipartida, um a um, um a zero ou difusão.
• O número de usuários individuais, conexões, transmissões publicadas e inscritos nas transmissões da reunião. Se houver Usuários do SIP Em relação à reunião, o número de usuários do SIP também é indicado.
• O número total de minutos transmitidos na reunião.
• O número de ocorrências do problema na reunião.
• O número de SDKs diferentes da Video API da Vonage utilizados na reunião. Passe o mouse sobre a entrada “SDKs” para ver uma lista dos diferentes SDKs e o número de usuários de cada um.
• O número de endpoints diferentes utilizados na reunião. Um endpoint pode ser uma versão de navegador (como o Chrome 98) para clientes que utilizam o OpenTok.js; um SDK da Video API da Vonage para iOS, Android, Linux ou Windows; ou SIP. Passe o mouse sobre a entrada “Endpoints” para ver uma lista dos diferentes endpoints e o número de usuários de cada um.

Dados do usuário

Ao depurar uma sessão problemática, geralmente é útil entender “quem é quem” no Inspector. Por exemplo, um dos participantes da sessão pode ter enfrentado problemas de conectividade; nesse caso, seria interessante visualizar os dados desse usuário específico no Inspector para entender melhor por que o problema pode ter ocorrido. Para auxiliar nessa identificação, o módulo Dados do Usuário fornece algumas informações gerais sobre cada usuário, incluindo sua localização, dispositivo, SDK e o número de erros que ele enfrentou.

Você pode clicar em um usuário para ver mais informações sobre ele, incluindo detalhes sobre seu conexões e correntes que eles publicaram. Essa perspectiva é especialmente útil para compreender que se inscreveram com sucesso para qualquer stream específico, o que você pode ver na coluna mais à direita da lista de streams.

Clique no Veja mais detalhes clique no link à direita da lista para ver mais informações sobre as transmissões e conexões do usuário. Para cada conexão, isso inclui o seguinte:

• A hora e a duração da conexão
• O tipo de transporte para a conexão
• Independentemente de a conexão utilizar o IPs permitidos recurso
• O sistema, seja um navegador (como o Chrome) ou um Client SDK nativo da Video API
• O agente do usuário (para um cliente baseado na web)

Para cada fluxo, os detalhes adicionais incluem o seguinte:

• A hora e a duração da transmissão
• A fonte do vídeo da transmissão (como “câmera” ou “compartilhamento de tela”)
• Se o stream utiliza o vídeo escalável recurso
• O sistema, seja um navegador (como o Chrome) ou um Client SDK nativo da Video API
• O agente do usuário (para um cliente baseado na web)

A tabela “Usuários” exibe um GUID (identificador globalmente único) para cada usuário. Esse GUID é reutilizado para identificar o mesmo usuário em várias conexões a uma sessão. Por exemplo, se um usuário do Client SDK se reconectar a uma sessão em várias sessões do navegador, o Inspector listará as conexões separadas sob a mesma entrada de usuário na tabela “Usuários”. Use o ID da conexão para identificar a conexão do cliente com a sessão. (Você pode usar os Client SDKs para obter o ID da conexão de um usuário.)

Os clientes SIP são identificados como “SIP” na tabela (por exemplo, “SIP1” e “SIP2”). Clique na seta de expansão ( > ) à esquerda do cliente SIP listado para ver detalhes adicionais. E clique no Veja mais detalhes Clique aqui para ver o ID da chamada SIP, o ID da conferência, o URI SIP e muito mais.

Para saber mais sobre como os clientes se conectam, publicam e se inscrevem, consulte Noções básicas sobre a Video API.

Registro de erros

Caso tenham ocorrido erros na sessão, eles serão exibidos na seção “Registro de erros”. Essa seção também exibe a taxa de falhas nas tentativas de conexão, publicação e assinatura realizadas na sessão ou reunião. Essa taxa é calculada dividindo-se o número de falhas pelo número total de tentativas.

Métricas de qualidade

O módulo Métricas de Qualidade é útil para compreender taxa de bits, perda de pacotes, e latência ao longo do tempo para cada usuário. Embora essas estatísticas não possam determinar diretamente a qualidade subjetiva percebida pelos usuários do seu aplicativo, elas podem ajudar a entender o que pode ter contribuído para a baixa qualidade. Você encontra uma breve explicação sobre cada um desses Concepts a seguir:

Observação: O módulo Métricas de Qualidade exibe dados apenas para clientes que não utilizam o protocolo SIP. Para visualizar dados de qualidade de clientes SIP, consulte Métricas de qualidade da interconexão SIP.

Taxa de bits — isso representa a quantidade de bits (dados) que estão sendo enviados pela conexão do usuário. O gráfico de Métricas de Qualidade inclui tanto a taxa de bits de áudio quanto a de vídeo, além da taxa de bits combinada. Passe o mouse sobre qualquer ponto de uma linha traçada para ver essas taxas de bits em um determinado momento, juntamente com o codec de vídeo, a resolução e a taxa de quadros (para uma transmissão que inclua vídeo). Embora a taxa de bits não possa ser diretamente associada à qualidade, taxas de bits muito baixas (menos de 150 kbps para vídeo e menos de 25 kbps para áudio) geralmente indicam baixa qualidade. Para entender melhor qual qualidade esperar com base nessas taxas de bits, consulte nosso Artigo da Central de Ajuda.

Perda de pacotes — em uma videochamada, os dados são enviados em unidades chamadas pacotes. Em muitas situações, alguns desses pacotes se perdem durante o trânsito, o que significa que não são recebidos pelo terminal do usuário. A perda de pacotes é calculada como a porcentagem de pacotes perdidos em relação ao total de pacotes enviados. Por exemplo, se 100 pacotes forem enviados e apenas 99 forem recebidos, há uma perda de pacotes de 1%. É normal que haja uma pequena perda de pacotes em uma videochamada sem que isso cause problemas de qualidade, mas se ela ultrapassar 3 a 5%, há uma boa chance de que a qualidade seja prejudicada.

Latência — isso representa o tempo que um pacote de dados leva para ir de um ponto final a outro. Qualquer latência superior a 300 ms provavelmente terá um efeito negativo na qualidade.

Você pode clicar e arrastar no gráfico para ampliar uma seção específica dele. É possível filtrar quais dados são exibidos usando as caixas de seleção acima do gráfico: Mostrar vídeo, Mostrar áudio, Editores e Inscritos. Você também pode filtrar por usuários usando as opções de filtro no lado esquerdo da página.

Observação: Para um fluxo que não utiliza vídeo escalável (como uma transmissão em uma sessão retransmitida), o emissor adapta o vídeo publicado para atender ao assinante com as piores condições de rede. O Inspector exibirá informações de qualidade com base nesse assinante com pior desempenho. Portanto, a qualidade do vídeo do emissor relatada pode não refletir a qualidade real do vídeo percebida por todos os assinantes da transmissão.

Para uma transmissão que utiliza vídeo escalável, o Inspector exibe informações sobre a qualidade do vídeo com base na conexão entre o editor da transmissão e o OpenTok Media Router.

A qualidade de áudio do emissor reflete sempre o que o pior assinante relata. Isso significa que a qualidade de áudio do emissor relatada pode não refletir a qualidade de áudio real percebida por todos os assinantes da transmissão.

Consulte este artigo para obter mais informações sobre vídeo escalável.

Métricas de qualidade da interconexão SIP

O módulo “Métricas de Qualidade de Interconexão SIP” oferece taxa de bits, perda de pacotes, latência, e MOS Dados do (Índice Médio de Satisfação) ao longo do tempo para cada cliente SIP na sessão. As métricas de qualidade referem-se à chamada SIP, e não ao fluxo WebRTC.

O Inspector exibe o módulo “Métricas de Qualidade de Interconexão SIP” apenas para sessões que incluem clientes SIP.

Em cada gráfico, você pode passar o mouse sobre qualquer ponto de uma linha traçada para ver cada valor em um determinado momento. O ID da conexão O valor exibido corresponde ao ID de conexão do cliente SIP na sessão da Video API da Vonage. Esse ID de conexão é retornado no Chamada à API REST para iniciar uma conexão SIP na sessão da Video API (ou nas chamadas correspondentes nos SDKs do servidor da Video API da Vonage).

Taxa de bits — Isso representa a quantidade de bits (dados) que estão sendo enviados e recebidos pelo gateway SIP da Video API da Vonage. É possível alternar entre a taxa de bits de áudio e de vídeo. Embora a taxa de bits não possa ser diretamente associada à qualidade, taxas de bits muito baixas geralmente estão associadas a uma qualidade inferior.

Perda de pacotes — Os dados SIP são enviados em unidades chamadas pacotes. Este gráfico mostra a perda de pacotes (em porcentagem) para cada conexão SIP na sessão. A perda de pacotes apresentada refere-se aos dados enviados e recebidos pelo gateway SIP da Video API da Vonage.

Latência — Isso representa a latência dos dados SIP enviados e recebidos pelo gateway SIP da Video API da Vonage. Qualquer latência superior a 300 ms provavelmente terá um efeito negativo na qualidade.

MOS — O Índice de Opinião Média (MOS) é uma medida objetiva da qualidade geral da chamada percebida pelo usuário. A escala varia de 1, representando má qualidade da chamada, a 5, significando excelente qualidade da chamada. Geralmente, as pontuações de MOS variam entre 3 e 4,5 para uma qualidade aceitável. Esse valor pode depender de alguns fatores, incluindo o codec utilizado na chamada.

Você pode clicar e arrastar no gráfico para ampliar uma seção específica dele. É possível filtrar quais dados são exibidos usando as caixas de seleção acima do gráfico: “Mostrar vídeo” e “Mostrar áudio”. Você também pode filtrar por usuários SIP usando as opções de filtro no lado esquerdo da página.

Informações sobre a transmissão

O módulo “Informações da transmissão” fornece informações sobre as transmissões na sessão. Se houver várias transmissões, selecione o ID da transmissão de seu interesse, no lado direito do cabeçalho “Informações da transmissão”. Clique na seta ( > ) à esquerda do cabeçalho para visualizar as informações, incluindo a resolução da transmissão, o tipo de transmissão (HLS e/ou RTMP), a duração da transmissão e o número total de bytes transmitidos.

Registro de Eventos

O Log de Eventos lista os eventos relacionados à conexão, publicação e assinatura que ocorreram na sessão ou reunião que você está analisando. Isso ajuda a compreender o contexto das falhas de conexão, publicação ou assinatura e também pode ser útil para identificar rapidamente por que os usuários se desconectam, cancelam a publicação ou cancelam a assinatura.

Você pode filtrar eventos usando o filtro de texto no canto superior esquerdo, de duas maneiras:

• Para visualizar apenas os eventos que incluem uma sequência de caracteres específica, por exemplo, “connect”, basta digitar essa sequência no campo de filtro de texto e clicar no símbolo “+”.
• Para excluir todos os eventos que contenham uma sequência de caracteres específica, digite essa sequência no campo de filtro de texto e clique no símbolo “-”.

Você também pode filtrar por usuário usando os filtros da barra lateral do Inspector.

Legendas em tempo real

Uma visualização específica para analisar os insights do Live Caption, que oferece:

• Uma aba exclusiva quando há eventos de legenda.
• Linha do tempo das legendas para mostrar quando as legendas estavam ativadas ou desativadas durante uma sessão.
• Visibilidade das atividades de legendas de emissores/assinantes com controles simples de filtragem.

Sessões x Reuniões

Todas as interações do OpenTok ocorrem dentro de uma sessão (para mais informações sobre isso, consulte Noções básicas sobre a Video API) — você pode pensar em uma sessão como uma “sala”. As sessões são criadas usando o OpenTok SDKs de servidor ou API REST, e cada sessão está associada a um ID de sessão.

Embora recomendemos gerar uma nova sessão para cada “reunião” entre os participantes — por exemplo, quando uma equipe se reúne para uma conferência em grupo —, às vezes os IDs de sessão são reutilizados em várias “reuniões”. Essa reutilização de sessões pode causar problemas ao depurar uma sessão no Inspector, pois é difícil identificar um usuário ou um problema ao visualizar várias reuniões ao mesmo tempo.

Reuniões no Inspector

Para facilitar a depuração desse tipo de sessão, o Inspector divide automaticamente as sessões em várias reuniões. Quando todos os participantes se desconectam de uma sessão, a reunião é considerada “encerrada”; e, se novos (ou os mesmos) participantes entrarem na sessão posteriormente, uma nova reunião é criada e exibida no Inspector.

Por padrão, o Inspector exibe todos reuniões quando uma nova sessão é carregada. Para acessar uma reunião específica, use o menu suspenso de reuniões no canto superior direito do Inspector.

Conexões, usuários e fluxos no Inspector

Conexões e fluxos fazem parte da funcionalidade principal do OpenTok. Esta seção irá explicar como esses objetos (juntamente com o objeto “usuário”) são referenciados no Inspector; no entanto, se você desejar uma visão geral mais abrangente desses conceitos, consulte Noções básicas sobre a Video API.

Conexões

Para participar de uma sessão do OpenTok, é necessário estabelecer uma conexão entre um cliente e a plataforma OpenTok (exceto em um transmitido sessão, na qual os clientes se conectam diretamente). Essa conexão está associada a um ID de conexão exclusivo. O ID de conexão é importante ao depurar uma sessão no Inspector, pois qualquer fluxo publicado na sessão está associado à conexão a partir da qual foi publicado. Para saber mais sobre como os clientes se conectam, publicam e se inscrevem, consulte Noções básicas sobre a Video API.

É possível visualizar os IDs das conexões e os fluxos associados a elas no Dados do usuário seção do Inspector. Você também pode verificar a qualidade de cada conexão na Métricas de qualidade seção do Inspetor.

Importante — problema conhecido: O Inspector exibe informações incorretas clientDisconnection eventos para os dois primeiros usuários em uma sessão roteada quando eles passam da transmissão ponto a ponto para o uso do Media Router durante o roteamento adaptativo de mídia. Consulte as informações sobre roteamento adaptativo de mídia nesta documentação roteamento adaptativo de mídia.

Usuários

Para facilitar a correlação das conexões com os usuários finais reais em uma sessão, o Inspector também inclui um objeto de usuário. O usuário está associado a um ponto de extremidade de cliente exclusivo — por exemplo, o navegador ou dispositivo móvel de um usuário final — rastreado por meio de cookies. Embora um usuário final possa ter várias conexões (caso se desconecte e se reconecte várias vezes), ele sempre estará associado a apenas um usuário no Inspector.

O objeto “usuário” no Inspector inclui algumas propriedades para facilitar a identificação de quem é quem:

• Localização — de onde o usuário se conectou (por exemplo, São Francisco, CA)
• Sistema — o navegador e/ou dispositivo a partir do qual o usuário se conectou (por exemplo, Chrome, macOS)
• SDK — o SDK do OpenTok utilizado pelo aplicativo cliente do usuário (por exemplo, JS-2.28.1)
• Região do servidor — a região do servidor OpenTok utilizada (por exemplo, Califórnia)
• Tempo de conexão — tempo em que o usuário esteve conectado e desconectado da sessão (incluindo o tempo de conexão)
• IP permitido — se a conexão utiliza o Recurso de lista de IPs permitidos opção ou não

Isso é especialmente útil ao tentar depurar um problema que afetou apenas um usuário específico. Depois de identificar o usuário no Inspector com base na localização/dispositivo, você pode examinar as conexões e os fluxos desse usuário para identificar problemas de qualidade ou de conectividade.

É importante observar que um usuário pode ter várias conexões, mas uma conexão não pode ter vários usuários. Você pode visualizar as informações do usuário, bem como suas conexões e transmissões associadas, no Dados do usuário seção do Inspetor.

Fluxos

Depois de conectado a uma sessão, o usuário pode publicar a fluxo e inscrever-se a outros fluxos publicados na sessão. Cada fluxo está associado a um ID de fluxo, que pode ser usado no Inspector para verificar quem, em uma sessão, publicou e se inscreveu com sucesso em um fluxo. O Inspector fornece diversas informações sobre os fluxos:

• A seção “Dados do usuário” fornece informações sobre quem publicou e quem se inscreveu nos feeds.
• A seção “Métricas de Qualidade” fornece informações e tendências sobre a qualidade das transmissões.
• A seção “Registro de Eventos” fornece informações cronológicas sobre os fluxos que estão sendo publicados, aos quais há assinaturas e que estão sendo excluídos.

Análise de sessões extensas

Se uma sessão incluir mais de 25 assinantes, o tipo de informação exibida no Inspector será alterado, incluindo a adição de dois módulos, descritos a seguir:

Resumo da conexão
Esta seção apresenta uma linha do tempo visual das tentativas de conexão, dos acertos e das falhas ocorridas na sessão.

Resumo dos assinantes
Esta seção apresenta uma linha do tempo visual das tentativas de assinatura, bem-sucedidas e malsucedidas, realizadas durante a sessão.

Também é importante observar que os assinantes não aparecem na seção “Métricas de Qualidade” para sessões grandes. Isso foi implementado para melhorar o tempo de carregamento em sessões grandes — se o Inspector tentasse carregar visualizações de alta qualidade para mais de 100 assinantes, a ferramenta levaria até uma hora ou mais para carregar todos os dados, afetando significativamente a usabilidade.

Salvar sessões

Por padrão, é possível consultar as sessões por até 20 dias a partir do término de uma sessão (consulte Retenção de dados e latência). Dentro desse prazo de retenção de 20 dias, você pode salvar uma sessão e continuar a inspecioná-la por até 24 meses.

Para salvar uma sessão, visualize-a no Inspector e clique no botão (Salvar) no cabeçalho da página. Insira um nome para a sessão salva (obrigatório) e defina até três tags personalizadas (opcional).

Observação: Recomendamos usar o campo “nome da sessão” como uma forma descritiva de diferenciar suas sessões. Use tags para registrar características específicas das sessões. Essas características podem incluir erros, características distintas da rede e atributos de qualidade observados durante a sessão.

Para visualizar uma sessão salva, acesse o Painel de Sessões e clique na aba “Sessões Salvas”.

É possível salvar até 1.000 sessões por Account.

Para editar o nome ou a tag de uma sessão, visualize a sessão no Inspector e clique no botão (Editar) no cabeçalho da página.

Se uma sessão estiver salva e ainda estiver dentro do período de retenção de 20 dias do Inspector, você poderá substituir os dados da sessão salva anteriormente por informações atualizadas acessando a página do Inspector correspondente a essa sessão e clicando no botão (Salvar) no cabeçalho da página.

Para excluir uma sessão da lista de sessões salvas:

• Visualize a sessão no Inspector e clique no botão (Excluir) no cabeçalho da página.
• Visualize a lista de “Sessões salvas” no Painel de Sessões e clique no botão (Excluir) da sessão que deseja excluir. Ou selecione várias sessões e clique no botão “Excluir selecionados”, localizado na parte superior da lista de “Sessões salvas”.

Observação: As sessões salvas ficam armazenadas por até 24 meses, e a Vonage se reserva o direito de excluir quaisquer sessões salvas com mais de 24 meses.

Problema conhecido: As sessões salvas entre 5 de dezembro de 2022 e 2 de março de 2023 não foram mantidas (e não podem ser consultadas). Corrigimos esse erro.

Retenção de dados e latência

Retenção de dados: 20 dias

**Observação:** O período de retenção é baseado na data e hora de criação de uma reunião dentro da sessão. As reuniões só podem ser consultadas dentro de um período de 7 dias da sessão. É melhores práticas para criar um novo ID de sessão para cada bate-papo por vídeo distinto em seu aplicativo.

Latência esperada: 5 minutos

Observação: Uma sessão pode conter várias reuniões. Uma nova reunião é agendada quando a sessão fica inativa por 10 minutos. Consulte a seção sobre Sessões x Reuniões para mais informações.

Você pode salvar uma sessão para visualizar seus dados após o período de retenção de dados de 20 dias. Consulte Salvar sessões.

Atualizações

26 de junho de 2025

As seguintes atualizações foram adicionadas ao Inspector:

• Novas descrições dos eventos “Acesso negado” na tabela “Usuário”.

• Nova visualização da pontuação MOS para assinantes.

  

• Nova visualização da pontuação MOS para fluxos de áudio e vídeo.

  

18 de março de 2025

As seguintes atualizações foram adicionadas ao Inspector:

• Detalhes aprimorados sobre o MOTIVO DO ENCERRAMENTO em Dados do usuário tabelas.

24 de janeiro de 2025

As seguintes atualizações foram adicionadas ao Inspector:

• Localização do servidor (cidade e país)
• Visualização das estatísticas das atas dos participantes para Clientes do Advanced Insights

7 de outubro de 2024

As seguintes atualizações foram adicionadas ao Inspector:

• Existe uma opção para selecionar o fuso horário. Consulte Guia do Inspetor.
• O Inspector agora inclui dados de resolução e taxa de quadros. Passe o mouse sobre qualquer ponto de uma linha traçada no gráfico de taxa de bits no Módulo de Métricas de Qualidade para visualizar os dados de resolução e taxa de quadros.
• O Inspector agora inclui dados sobre o uso da lista de IPs permitidos. Clique no Veja mais detalhes link à direita de uma conexão listada no Dados do usuário módulo para verificar se a conexão utiliza a lista de IPs permitidos.
• O Inspector agora também inclui dados de métricas de qualidade de interconexão SIP. Consulte Métricas de qualidade da interconexão SIP.