Observabilidade do cliente — Windows

• Visão geral
• Web
• iOS
• iOS (Swift)
• Android
• Windows
• Linux
• React Native

O SDK do OpenTok para Windows oferece chamadas para acessar estatísticas de rede e de mídia em tempo real durante uma sessão de vídeo. Essas chamadas fornecem métricas detalhadas sobre a qualidade do fluxo — como perda de pacotes, dados recebidos e largura de banda — e podem ser utilizadas em qualquer fluxo de emissor ou de assinante.

O SDK de vídeo da OpenTok disponibiliza métricas detalhadas sobre a qualidade do fluxo por meio de uma API de estatísticas de alto nível — recomendada para a maioria dos casos de uso —, que fornece estatísticas de áudio, vídeo, rede e do lado do remetente de forma unificada e sensível à sessão, mantendo-se estável durante as transições entre conexões entre pares. Para depuração avançada, o SDK também oferece acesso ao relatório de estatísticas brutas do WebRTC, que reflete dados não processados das conexões entre pares.

O SDK também disponibiliza métricas de condição de rede que oferecem uma avaliação geral do estado da conexão, tanto para emissores quanto para assinantes. Essas métricas incluem uma pontuação de condição de rede, o motivo por trás dessa pontuação e — para os assinantes — uma fonte de degradação que indica qual lado da conexão é responsável por quaisquer problemas observados. Consulte Condição da rede e fonte de degradação para mais detalhes.

Este guia inclui as seguintes seções:

• API de estatísticas de áudio, vídeo e links de mídia
• Estruturas estatísticas
• Estatísticas do lado do remetente
• Condição da rede e fonte de degradação
• Relatório de estatísticas da RTC

API de estatísticas de áudio, vídeo e links de mídia

O SDK do OpenTok para Windows envia estatísticas periódicas de áudio, vídeo e links de mídia tanto para os emissores quanto para os assinantes. Essas estatísticas incluem contagem de pacotes, taxas de bits, dados de taxa de quadros, métricas de pausa/congelamento, informações sobre codecs e métricas de rede no nível de transporte, como estimativa de largura de banda e pontuação das condições da rede.

As estatísticas são divulgadas por meio dos seguintes eventos:

• Publisher.AudioStatsUpdated — estatísticas de áudio do lado do editor
• Publisher.VideoStatsUpdated — estatísticas de vídeo do lado do editor
• Publisher.MediaLinkStatsUpdated — estatísticas de links de mídia do lado do editor (métricas de transporte)
• Publisher.VideoQualityChanged — notificação sobre alteração na qualidade do vídeo do editor
• Publisher.NetworkConditionChanged — notificação de alteração nas condições da rede de editores
• Subscriber.AudioStatsUpdated — estatísticas de áudio do lado do assinante
• Subscriber.VideoStatsUpdated — estatísticas de vídeo do lado do assinante
• Subscriber.MediaLinkStatsUpdated — estatísticas de conexão de mídia do lado do assinante (métricas de transporte)
• Subscriber.VideoQualityChanged — notificação sobre alteração na qualidade do vídeo para assinantes
• Subscriber.NetworkConditionChanged — notificação de alteração nas condições da rede do assinante

Para recebê-los, defina o manipulador de eventos apropriado no emissor ou no assinante.

Ativação de estatísticas para editores

Defina os manipuladores de eventos correspondentes para Publisher.AudioStatsUpdated e Publisher.VideoStatsUpdated:

publisher.AudioStatsUpdated += (sender, args) =>
{
    foreach (var stat in args.Stats)
    {
        Console.WriteLine($"Audio bytes sent: {stat.BytesSent}");
    }
};

publisher.VideoStatsUpdated += (sender, args) =>
{
    foreach (var stat in args.Stats)
    {
        Console.WriteLine($"Video packets sent: {stat.PacketsSent}");
    }
};

publisher.MediaLinkStatsUpdated += (sender, args) =>
{
    foreach (var stat in args.MediaLinkStats)
    {
        Console.WriteLine($"Publisher uplink bandwidth: {stat.Transport.ConnectionEstimatedBandwidth} bps");
        Console.WriteLine($"Network condition: {stat.Transport.Condition}");
        Console.WriteLine($"Condition reason: {stat.Transport.NetworkConditionReason}");
    }
};

Esses eventos são enviados periodicamente para relatar estatísticas de áudio e vídeo para o editor. Os manipuladores de eventos para esses eventos são passados em uma matriz de Estatísticas da Rede de Áudio e Estatísticas da Rede de Vídeos Cada método recebe dois objetos: o publisher e uma matriz de objetos de estatísticas. Para um publisher em uma sessão roteada (aquela que usa o Roteador de mídia OpenTok, o array inclui um objeto, definindo as estatísticas para o único fluxo de mídia de áudio ou vídeo enviado ao Vonage Video Media Router. Em uma sessão retransmitida, o array inclui um objeto para cada assinante do fluxo publicado.

Recebimento de eventos de qualidade de vídeo nos editores

Se você também estiver interessado em eventos relacionados à qualidade de vídeo, implemente este manipulador:

publisher.VideoQualityChanged += (sender, args) =>
{
    Console.WriteLine($"Publisher video quality changed: {args.Reason}");
};

Recebimento de eventos de alteração nas condições da rede nos editores

Para receber eventos de alteração nas condições da rede para o editor, inscreva-se no Publisher.NetworkConditionChanged evento:

publisher.NetworkConditionChanged += (sender, args) =>
{
    Console.WriteLine($"Publisher network condition: {args.MediaLinkStats.Transport.Condition}");
    Console.WriteLine($"Reason: {args.MediaLinkStats.Transport.NetworkConditionReason}");
};

Este evento é acionado quando é detectada uma alteração significativa nas condições da rede para o editor. Ele inclui as estatísticas atuais do link de mídia, juntamente com as métricas de transporte.

Ativação de estatísticas para assinantes

Defina os manipuladores de eventos correspondentes para Subscriber.AudioStatsUpdated e Subscriber.VideoStatsUpdated:

subscriber.VideoStatsUpdated += (sender, stats) =>
{
    Console.WriteLine($"Video bytes received: {stats.BytesReceived}");
};

subscriber.AudioStatsUpdated += (sender, stats) =>
{
    Console.WriteLine($"Audio packets received: {stats.PacketsReceived}");
};

subscriber.MediaLinkStatsUpdated += (sender, args) =>
{
    Console.WriteLine($"Local downlink bandwidth: {args.MediaLinkStats.Transport.ConnectionEstimatedBandwidth} bps");
    if (args.MediaLinkStats.RemotePublisherTransport != null)
    {
        Console.WriteLine($"Remote publisher uplink bandwidth: {args.MediaLinkStats.RemotePublisherTransport.ConnectionEstimatedBandwidth} bps");
    }
    Console.WriteLine($"Degradation source: {args.MediaLinkStats.NetworkDegradationSource}");
};

Recebimento de eventos relacionados à qualidade de vídeo nos assinantes

Se você também estiver interessado em eventos relacionados à qualidade de vídeo, implemente este manipulador:

subscriber.VideoQualityChanged += (sender, args) =>
{
    Console.WriteLine($"Subscriber video quality event: {args.Reason}");
};

Recebimento de eventos de alteração nas condições da rede no assinante

Para receber eventos de alteração nas condições da rede para o assinante, inscreva-se no Subscriber.NetworkConditionChanged evento:

subscriber.NetworkConditionChanged += (sender, args) =>
{
    Console.WriteLine($"Local network condition: {args.MediaLinkStats.Transport.Condition}");
    Console.WriteLine($"Remote publisher network condition: {args.MediaLinkStats.RemotePublisherTransport.Condition}");
    Console.WriteLine($"Degradation source: {args.MediaLinkStats.NetworkDegradationSource}");
};

Este evento é acionado quando é detectada uma alteração significativa nas condições da rede para o assinante ou para o editor remoto. Ele inclui as estatísticas atuais do link de mídia, com métricas de transporte locais e remotas e a origem da degradação.

Estruturas de dados estatísticos

Esta seção descreve as estruturas e os campos fornecidos pela API de estatísticas de áudio e vídeo do Windows Video SDK. Embora todas as plataformas do Video SDK ofereçam o mesmo conjunto de estatísticas, pode haver pequenas diferenças na forma como cada plataforma estrutura ou nomeia os campos individuais. Essas variações refletem convenções de design do SDK específicas de cada plataforma, e não diferenças nas métricas subjacentes.

Para obter uma explicação independente de plataforma sobre as estatísticas disponíveis e o que elas representam, consulte Visão geral da observabilidade do cliente.

TransportStats

Representa métricas no nível do transporte.

• ConnectionEstimatedBandwidth — Largura de banda estimada disponível da conexão (bps)
• Condition — Pontuação atual do estado da rede (NetworkCondition.Unknown, NetworkCondition.Critical, NetworkCondition.Warning, NetworkCondition.Fair, NetworkCondition.Good, ou NetworkCondition.Excellent)
• NetworkConditionReason — Principal motivo que afeta o estado da rede (NetworkReason.None, NetworkReason.Unknown, NetworkReason.Bandwidth, ou NetworkReason.PacketLoss)

Publisher.AudioNetworkStats

Fornece estatísticas sobre a faixa de áudio de um editor.

• ConnectionId — ID de conexão do assinante (apenas retransmitida)
• SubscriberId — ID do assinante (apenas retransmitido)
• PacketsLost — Total de pacotes de áudio perdidos
• PacketsSent — Total de pacotes de áudio enviados
• BytesSent — Total de bytes de áudio enviados
• Timestamp — Carimbo de data e hora em que as estatísticas foram coletadas (ms)
• StartTime — Carimbo de data/hora em que os totais acumulados começaram (ms)

Publisher.VideoNetworkStats

Fornece estatísticas sobre a trilha de vídeos de um editor.

• ConnectionId — ID de conexão do assinante (apenas retransmitida)
• SubscriberId — ID do assinante (apenas retransmitido)
• PacketsLost — Pacotes de vídeo perdidos
• PacketsSent — Pacotes de vídeo enviados
• BytesSent — Bytes de vídeo enviados
• Timestamp — Data e hora em que as estatísticas foram coletadas
• StartTime — Data e hora em que os totais acumulados começaram
• VideoLayers — Lista de camadas de transmissão simultânea/SVC (VideoLayerStats)

Publisher.VideoLayerStats

Representa uma única transmissão simultânea ou camada de vídeo SVC.

• Width — Largura do quadro codificado
• Height — Altura do quadro codificado
• EncodedFrameRate — Quadros codificados por segundo
• Bitrate — Taxa de bits da camada (bps)
• TotalBitrate — Taxa de bits, incluindo a sobrecarga do RTP (bps)
• ScalabilityMode — Descrição de SVC/escalabilidade (por exemplo, “L3T3”)
• QualityLimitationReason — Motivo da redução da qualidade
• Codec — Codec utilizado nesta camada

Publisher.PublisherMediaLinkStats

Fornece estatísticas no nível do transporte para a conexão de um editor.

• Transport — Estatísticas de tráfego para esta editora (veja TransportStats)

Subscriber.AudioNetworkStatsEventArgs

Fornece estatísticas sobre a trilha de áudio de um assinante.

• PacketsLost — Estimativa de pacotes de áudio perdidos
• PacketsReceived — Pacotes de áudio recebidos
• BytesReceived — Trechos de áudio recebidos
• Timestamp — Data e hora em que as estatísticas foram coletadas
• SenderStats — Estimativa da rede do lado do remetente (opcional)

Subscriber.VideoNetworkStatsEventArgs

Fornece estatísticas sobre a trilha de vídeo de um assinante.

• PacketsLost — Pacotes de vídeo perdidos
• PacketsReceived — Pacotes de vídeo recebidos
• BytesReceived — Bytes de vídeo recebidos
• Timestamp — Data e hora em que as estatísticas foram coletadas
• SenderStats — Estimativa da rede do lado do remetente (opcional)
• Width — Largura do quadro decodificado
• Height — Altura do quadro decodificado
• DecodedFrameRate — Quadros por segundo decodificados
• Bitrate — Taxa de bits do vídeo (bps)
• TotalBitrate — Taxa de bits total, incluindo a sobrecarga do RTP
• PauseCount — Número de pausas no vídeo (>5 s sem nenhum quadro)
• TotalPausesDuration — Duração total da pausa (ms)
• FreezeCount — Número de travamentos definidos pelo WebRTC
• TotalFreezesDuration — Duração total do congelamento (ms)
• Codec — Codec do decodificador

Subscriber.SubscriberMediaLinkStats

Fornece estatísticas no nível de transporte para as conexões de um assinante, incluindo visibilidade do desempenho da rede do editor remoto. Isso permite que as Applications diagnostiquem se os problemas de conexão se originam do downlink do assinante ou do uplink do editor.

• Transport — Estatísticas de transporte para a conexão de downlink deste assinante (consulte TransportStats)
• RemotePublisherTransport — Estatísticas de transporte para a conexão de uplink do editor remoto (consulte TransportStats). Pode ser limitado se as estatísticas do remetente não estiverem ativadas.
• NetworkDegradationSource — Indica a origem da degradação da rede, se houver (NetworkDegradationSource.None, NetworkDegradationSource.Local, NetworkDegradationSource.Remote, ou NetworkDegradationSource.BothOrUnclear)

Estatísticas do lado do remetente

Veja o Visão geral das estatísticas do lado do remetente.

Ativação das estatísticas do remetente

As estatísticas do remetente são recebidas pelos assinantes. Para receber essas estatísticas, habilite-as para o editor do fluxo definindo o HasSenderStatsTrack propriedade para true ao criar o editor:

var publisherBuilder = new Publisher.Builder()
{
    HasSenderStatsTrack = true
};

Publisher publisher = publisherBuilder.Build();

Se HasSenderStatsTrack Se não estiver habilitado, nenhum canal de estatísticas do remetente será publicado para esse editor. O valor padrão é false.

Recebimento de estatísticas do remetente

Se o editor tiver ativado as estatísticas do remetente, os assinantes as recebem automaticamente por meio do VideoStatsUpdated e AudioStatsUpdated eventos descrito acima. O SenderStats propriedade em ambos VideoNetworkStatsEventArgs e AudioNetworkStatsEventArgs apresenta duas métricas:

• ConnectionMaxAllocatedBitrate — A taxa de bits máxima que pode ser estimada para a conexão
• ConnectionEstimatedBandwidth — A largura de banda estimada atual para a conexão

Essas métricas são calculadas por pacote de áudio e vídeo; portanto, os mesmos valores aparecem tanto nas estatísticas de vídeo quanto nas de áudio.

subscriber.VideoStatsUpdated += (sender, stats) =>
{
    if (stats.SenderStats != null)
    {
        Console.WriteLine($"Connection max allocated bitrate: {stats.SenderStats.ConnectionMaxAllocatedBitrate}");
        Console.WriteLine($"Connection current estimated bandwidth: {stats.SenderStats.ConnectionEstimatedBandwidth}");
    }
};

Condição da rede e fonte de degradação

O SDK fornece métricas em tempo real sobre as condições da rede tanto para editores quanto para assinantes, incluindo uma pontuação de condição, o motivo por trás dessa pontuação e a origem da degradação para os assinantes. Para obter uma explicação completa sobre o modelo de condições da rede, as pontuações, os motivos e como ativá-lo, consulte o Visão geral da observabilidade do cliente.

Os dados sobre o estado da rede estão disponíveis por meio de dois canais:

• Estatísticas periódicas: As estatísticas de eventos de links de mídia incluem métricas de transporte com Condition e NetworkConditionReason. Para os assinantes, as estatísticas dos links de mídia também incluem RemotePublisherTransport e NetworkDegradationSource.
• Eventos relacionados a alterações nas condições da rede: Eventos específicos, tanto no emissor quanto no receptor, são acionados quando é detectada uma mudança significativa nas condições da rede.

O exemplo a seguir mostra como usar os dados de condição da rede do assinante para identificar a origem da degradação:

subscriber.NetworkConditionChanged += (sender, args) =>
{
    var localCondition = args.MediaLinkStats.Transport.Condition;
    var remoteCondition = args.MediaLinkStats.RemotePublisherTransport.Condition;
    var source = args.MediaLinkStats.NetworkDegradationSource;

    if (source == NetworkDegradationSource.Local)
    {
        Console.WriteLine($"Local network is degraded (condition: {localCondition})");
    }
    else if (source == NetworkDegradationSource.Remote)
    {
        Console.WriteLine($"Remote publisher network is degraded (condition: {remoteCondition})");
    }
    else if (source == NetworkDegradationSource.BothOrUnclear)
    {
        Console.WriteLine($"Degradation source unclear — local: {localCondition}, remote: {remoteCondition}");
    }
};

Relatório de estatísticas da RTC

Utilize a API de estatísticas do RTC para obter dados de diagnóstico no nível do WebRTC. Para obter estatísticas de conexão entre pares de baixo nível de um publisher, utilize a Publisher.GetRtcStatsReport() método. Isso fornece relatórios de estatísticas RTC para o fluxo de mídia. Trata-se de uma operação assíncrona. Quando as estatísticas estiverem disponíveis, o evento RtcStatsReport é enviado. O objeto RtcStatsReportArgs inclui uma matriz de EditorRtcStats objetos, que incluem uma propriedade JsonArrayOfReports. Trata-se de um array JSON de relatórios de estatísticas do RTC, cujo formato é semelhante ao do objeto RtcStatsReport implementado nos navegadores da web (consulte esses documentos da Mozilla. Veja também esta documentação do W3C.

Para obter estatísticas de conexão entre pares de baixo nível de um assinante, use o Subscriber.GetRtcStatsReport() método. Isso fornece um relatório de estatísticas RTC para o fluxo de mídia. Trata-se de uma operação assíncrona. Quando as estatísticas estiverem disponíveis, o evento RtcStatsReport é enviado. RtcStatsReportArgs O objeto inclui uma propriedade chamada JsonArrayOfReports. Trata-se de um array JSON de relatórios de estatísticas do RTC, que são semelhantes ao formato do objeto RtcStatsReport implementado nos navegadores da web (consulte esses documentos da Mozilla. Veja também esta documentação do W3C.

Solicitação de um relatório de estatísticas do RTC para um editor:

publisher.RtcStatsReport += (sender, args) =>
{
    foreach (var stat in args.stats)
    {
        Console.WriteLine(stat.JsonArrayOfReports); // Raw RTC JSON
    }
};

publisher.GetRtcStatsReport();