Observabilidade do cliente — iOS

O SDK do OpenTok para iOS 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 stream — como perda de pacotes, dados recebidos e largura de banda — e podem ser utilizadas em qualquer stream 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 e degradação da rede 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
Aplicativo de exemplo

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

O SDK do OpenTok para iOS 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 disponibilizadas por meio de:

OTPublisherKitNetworkStatsDelegate — estatísticas do lado do editor (áudio, vídeo)
OTSubscriberKitNetworkStatsDelegate — estatísticas do lado do assinante (áudio, vídeo)

Para recebê-los, habilite o delegado apropriado no editor ou no assinante.

Ativação de estatísticas para editores

Anexe uma classe que adote a interface `OTPublisherKitNetworkStatsDelegate`:

@interface MyViewController () <OTPublisherKitDelegate, OTPublisherKitNetworkStatsDelegate>
@end

OTPublisher *publisher = [[OTPublisher alloc] initWithDelegate:self
                                                      settings:settings];
publisher.networkStatsDelegate = self;

Implemente os callbacks:

- (void)publisher:(OTPublisherKit *)publisher
videoNetworkStatsUpdated:(NSArray<OTPublisherKitVideoNetworkStats *> *)statsArray {

    OTPublisherKitVideoNetworkStats *stats = statsArray.firstObject;
    if (!stats) return;

    // For routed sessions, the first element is sufficient.
    // For relayed sessions, iterate all elements if you want per-subscriber stats.
    NSString *connectionId = stats.connectionId ?: @"<none>";
    NSString *subscriberId = stats.subscriberId ?: @"<none>";

    NSLog(@"Publisher Video Stats for connectionId: %@, subscriberId: %@", connectionId, subscriberId);
    NSLog(@"Video bytes sent: %lld", stats.videoBytesSent);
    NSLog(@"Video packets sent: %lld", stats.videoPacketsSent);
    NSLog(@"Video packets lost: %lld", stats.videoPacketsLost);
    NSLog(@"Stats timestamp: %f ms", stats.timestamp);

    for (OTPublisherKitVideoLayerStats *layer in stats.videoLayers) {
        NSLog(@"Layer: %dx%d", layer.width, layer.height);
        NSLog(@"  Encoded FPS: %f", layer.encodedFrameRate);
        NSLog(@"  Bitrate: %lld bps", layer.bitrate);
        NSLog(@"  Total bitrate (incl. RTP overhead): %lld bps", layer.totalBitrate);
        NSLog(@"  Codec: %@", layer.codec ?: @"unknown");
        NSLog(@"  Scalability mode: %@", layer.scalabilityMode ?: @"none");
        NSLog(@"  Quality limitation: %@", @(layer.qualityLimitationReason));
    }
}

- (void)publisher:(OTPublisherKit *)publisher
audioNetworkStatsUpdated:(NSArray<OTPublisherKitAudioNetworkStats *> *)statsArray {

    OTPublisherKitAudioNetworkStats *stats = statsArray.firstObject;
    if (!stats) return;

    // For routed sessions, the first element is sufficient.
    // For relayed sessions, iterate all elements if you want per-subscriber stats.
    NSString *connectionId = stats.connectionId ?: @"<none>";
    NSString *subscriberId = stats.subscriberId ?: @"<none>";

    NSLog(@"Publisher Audio Stats for connectionId: %@, subscriberId: %@", connectionId, subscriberId);
    NSLog(@"Audio bytes sent: %lld", stats.audioBytesSent);
    NSLog(@"Audio packets sent: %lld", stats.audioPacketsSent);
    NSLog(@"Audio packets lost: %lld", stats.audioPacketsLost);
    NSLog(@"Stats timestamp: %f ms", stats.timestamp);
}

- (void)publisher:(OTPublisherKit *)publisher
mediaLinkStatsUpdated:(NSArray<OTPublisherKitMediaLinkStats*>*)mediaLinkStats {
    
    if (mediaLinkStats.count == 0) return;
    OTPublisherKitMediaLinkStats *stats = mediaLinkStats.firstObject;
    
    NSLog(@"Publisher uplink bandwidth: %lld bps", stats.transport.connectionEstimatedBandwidth);
    NSLog(@"Network condition: %ld", (long)stats.transport.networkCondition);
    NSLog(@"Condition reason: %ld", (long)stats.transport.networkConditionReason);
}

Para um editor em uma sessão roteada (aquela que utiliza o Roteador de mídia de vídeo da Vonage, a matriz `stats` inclui um objeto, definindo as estatísticas para o fluxo de mídia de áudio ou vídeo único que é enviado ao Vonage Video Media Router. Em uma sessão retransmitida, a matriz `stats` 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 do vídeo, implemente esta função de retorno de chamada:

- (void)publisher:(OTPublisherKit *)publisher
videoQualityChanged:(OTPublisherKitVideoNetworkStats *)stats
           reason:(OTPublisherVideoEventReason)reason {

    NSLog(@"Publisher video quality event: %ld", (long)reason);
}

Recebimento de eventos de condição de rede nos editores

Para receber eventos de alteração nas condições da rede para o editor, implemente o publisher:networkConditionChanged:mediaLinkStats:reason: função de retorno:

- (void)publisher:(OTPublisherKit *)publisher
networkConditionChanged:(OTPublisherKitMediaLinkStats *)mediaLinkStats
             reason:(OTNetworkReason)reason {

    NSLog(@"Publisher network condition changed: %ld", (long)mediaLinkStats.transport.networkCondition);
    NSLog(@"Reason: %ld", (long)mediaLinkStats.transport.networkConditionReason);
}

Essa função de retorno de chamada é acionada quando é detectada uma alteração significativa nas condições de rede do editor. Ela inclui as estatísticas atuais do link de mídia, juntamente com as métricas de transporte. Consulte Condição da rede e fonte de degradação para obter mais detalhes sobre como interpretar as pontuações e os motivos relativos às condições da rede.

Ativação de estatísticas para assinantes

Anexe uma classe que adote OTSubscriberKitNetworkStatsDelegate:

@interface MyViewController () <OTSubscriberKitDelegate, OTSubscriberKitNetworkStatsDelegate>
@end

OTSubscriber *subscriber = [[OTSubscriber alloc] initWithStream:stream
                                                       delegate:self];
subscriber.networkStatsDelegate = self;
[session subscribe:subscriber error:nil];

Implemente os callbacks:

- (void)subscriber:(OTSubscriberKit *)subscriber
videoNetworkStatsUpdated:(OTSubscriberKitVideoNetworkStats *)stats {
    NSLog(@"Video bytes received: %llu", stats.videoBytesReceived);
}

- (void)subscriber:(OTSubscriberKit *)subscriber
audioNetworkStatsUpdated:(OTSubscriberKitAudioNetworkStats *)stats {
    NSLog(@"Audio packets received: %llu", stats.audioPacketsReceived);
}

- (void)subscriber:(OTSubscriberKit *)subscriber
mediaLinkStatsUpdated:(OTSubscriberKitMediaLinkStats *)mediaLinkStats {
    
    NSLog(@"Local downlink bandwidth: %lld bps", mediaLinkStats.transport.connectionEstimatedBandwidth);
    NSLog(@"Remote publisher uplink bandwidth: %lld bps", mediaLinkStats.remotePublisherTransport.connectionEstimatedBandwidth);
    NSLog(@"Degradation source: %ld", (long)mediaLinkStats.networkDegradationSource);
}

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

Além disso, tratar os eventos relacionados à alteração da qualidade de vídeo dos assinantes:

- (void)subscriber:(OTSubscriberKit *)subscriber
videoQualityChanged:(OTSubscriberKitVideoNetworkStats *)stats
            reason:(OTSubscriberVideoEventReason)reason {

    NSLog(@"Subscriber video quality event: %ld", (long)reason);
}

Recebimento de eventos de condição da rede no assinante

Para receber eventos de alteração nas condições da rede para o assinante, implemente o subscriber:networkConditionChanged:mediaLinkStats:reason: função de retorno:

- (void)subscriber:(OTSubscriberKit *)subscriber
networkConditionChanged:(OTSubscriberKitMediaLinkStats *)mediaLinkStats
             reason:(OTNetworkReason)reason {

    NSLog(@"Local network condition: %ld", (long)mediaLinkStats.transport.networkCondition);
    NSLog(@"Remote publisher network condition: %ld", (long)mediaLinkStats.remotePublisherTransport.networkCondition);
    NSLog(@"Degradation source: %ld", (long)mediaLinkStats.networkDegradationSource);
}

Essa função de retorno de chamada é acionada quando é detectada uma alteração significativa nas condições da rede para o assinante ou para o editor remoto. Ela inclui as estatísticas atuais do link de mídia, com métricas de transporte locais e remotas e a origem da degradação. Consulte Condição da rede e fonte de degradação para obter mais detalhes sobre como interpretar as pontuações e os motivos relativos às condições da rede.

Estruturas de dados estatísticos

Esta seção descreve as estruturas e propriedades fornecidas pela API de estatísticas de áudio e vídeo do iOS. Embora todas as plataformas do SDK de vídeo apresentem 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.

`OTTransportStats`

Representa métricas compartilhadas no nível do transporte.

connectionEstimatedBandwidth – Largura de banda estimada disponível para conexão (bps).
networkCondition – Pontuação atual do estado da rede (OTNetworkConditionUnknown, OTNetworkConditionCritical, OTNetworkConditionWarning, OTNetworkConditionFair, OTNetworkConditionGood, ou OTNetworkConditionExcellent).
networkConditionReason – Principal motivo que afeta o estado da rede (OTNetworkReasonNone, OTNetworkReasonUnknown, OTNetworkReasonBandwidth, OTNetworkReasonPacketLoss, ou OTNetworkReasonNetworkConditionChange).

`OTPublisherKitVideoNetworkStats`

Fornece estatísticas sobre a trilha de vídeo de um editor. Inclui:

connectionId – Em uma sessão retransmitida, o ID de conexão do cliente que está assinando o fluxo. Não definido em uma sessão roteada.
subscriberId – Em uma sessão retransmitida, o ID de assinatura do cliente que está assinando o fluxo. Não definido em uma sessão roteada.
videoPacketsLost – Estimativa de pacotes de vídeo perdidos.
videoPacketsSent – Pacotes de vídeo enviados.
videoBytesSent – Bytes de vídeo enviados.
timestamp – Carimbo de data/hora do Unix, em milissegundos, no momento em que as estatísticas foram coletadas.
startTime – O carimbo de data e hora, em milissegundos desde a época Unix, a partir do qual os totais acumulados começaram a ser calculados.
videoLayers – A matriz de estatísticas da camada de vídeo (consulte OTPublisherKitVideoLayerStats).

`OTPublisherKitAudioNetworkStats`

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

connectionId – Em uma sessão retransmitida, o ID de conexão do cliente que está assinando o fluxo. Não definido em uma sessão roteada.
subscriberId – Em uma sessão retransmitida, o ID de assinatura do cliente que está assinando o fluxo. Não definido em uma sessão roteada.
audioPacketsLost – Estimativa de pacotes perdidos.
audioPacketsSent – Pacotes de áudio enviados.
audioBytesSent – Trechos de áudio enviados.
timestamp – Carimbo de data/hora do Unix em milissegundos.
startTime – O carimbo de data e hora, em milissegundos desde a época Unix, a partir do qual os totais acumulados começaram a ser calculados.

`OTPublisherKitVideoLayerStats`

Representa uma camada de transmissão simultânea ou uma camada 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 da camada, incluindo a sobrecarga do RTP (bps).
scalabilityMode – Descritor SVC/escalabilidade (por exemplo, “L3T3”).
qualityLimitationReason – Motivo da limitação de qualidade (largura de banda, CPU, codec, resolução ou mudança de camada).
codec – O codec utilizado por essa camada de vídeo.

`OTSenderStats`

Métricas de estimativa do lado do remetente (aplicadas tanto ao áudio quanto ao vídeo).

connectionMaxAllocatedBitrate – Taxa de bits máxima estimada para a conexão do remetente.
connectionEstimatedBandwidth – Estimativa da largura de banda atual (bps).

`OTSubscriberKitVideoNetworkStats`

Fornece estatísticas sobre a trilha de vídeos de um assinante. Inclui:

videoPacketsLost – Estimativa de pacotes de vídeo perdidos.
videoPacketsReceived – Pacotes de vídeo recebidos.
videoBytesReceived – Bytes de vídeo recebidos.
timestamp – Carimbo de data/hora do Unix, em milissegundos, no momento em que as estatísticas foram coletadas.
senderStats – Métricas do lado do remetente (opcional).
width – Largura do quadro decodificado em pixels.
height – Altura do quadro decodificado em pixels.
decodedFrameRate – Quadros por segundo decodificados.
bitrate – Taxa de bits do vídeo (bps).
totalBitrate – Taxa de bits, incluindo a sobrecarga do RTP (bps).
pauseCount – Número de pausas (mais de 5 s desde o último quadro). Inclui desativações intencionais e casos de recurso alternativo de áudio.
totalPausesDuration – Duração total da pausa (ms).
freezeCount – Contagem de congelamentos (evento de congelamento definido pelo WebRTC).
totalFreezesDuration – Duração total do congelamento (ms).
codec – Codec atual do decodificador.

`OTSubscriberKitAudioNetworkStats`

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

audioPacketsLost – Estimativa de pacotes perdidos.
audioPacketsReceived – Pacotes recebidos.
audioBytesReceived – Bytes recebidos.
timestamp – Carimbo de data/hora do Unix em milissegundos.
senderStats – Métricas do lado do remetente (opcional).

`OTPublisherKitMediaLinkStats`

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

transport – Estatísticas de tráfego para esta editora (ver OTTransportStats)

`OTSubscriberKitMediaLinkStats`

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 (ver OTTransportStats)
remotePublisherTransport – Estatísticas de transporte para a conexão de uplink do editor remoto (consulte OTTransportStats). Pode ser limitado se as estatísticas do remetente não estiverem ativadas.
networkDegradationSource – Indica a origem da degradação da rede, se houver (OTNetworkDegradationSourceNone, OTNetworkDegradationSourceLocal, OTNetworkDegradationSourceRemote, ou OTNetworkDegradationSourceBothOrUnclear)

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 senderStatsTrack propriedade para true para o OTPublisherKitSettings objeto usado para criar o editor.

OTPublisherKitSettings *settings = [[OTPublisherKitSettings alloc] init];
settings.senderStatsTrack = YES;

OTPublisher *publisher = [[OTPublisher alloc] initWithDelegate:self
                                                      settings:settings];

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

Recebimento de estatísticas do remetente

Se o editor tiver ativado as estatísticas do remetente, os assinantes as recebem automaticamente por meio do OTSubscriberKitNetworkStatsDelegate callbacks descrito acima. O senderStats propriedade em ambos OTSubscriberKitVideoNetworkStats e OTSubscriberKitAudioNetworkStats 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.

- (void)subscriber:(OTSubscriberKit *)subscriber
videoNetworkStatsUpdated:(OTSubscriberKitVideoNetworkStats *)stats
{
    if (stats.senderStats) {
        OTSenderStats *sender = stats.senderStats;
        NSLog(@"Connection max allocated bitrate: %lld bps", (long long)sender.connectionMaxAllocatedBitrate);
        NSLog(@"Connection current estimated bandwidth: %lld bps", (long long)sender.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 networkCondition 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: Callbacks específicos, tanto no emissor quanto no assinante, 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:

- (void)subscriber:(OTSubscriberKit *)subscriber
networkConditionChanged:(OTSubscriberKitMediaLinkStats *)mediaLinkStats
             reason:(OTNetworkReason)reason {

    OTNetworkCondition localCondition = mediaLinkStats.transport.networkCondition;
    OTNetworkCondition remoteCondition = mediaLinkStats.remotePublisherTransport.networkCondition;
    OTNetworkDegradationSource source = mediaLinkStats.networkDegradationSource;

    if (source == OTNetworkDegradationSourceLocal) {
        NSLog(@"Local network is degraded (condition: %ld)", (long)localCondition);
    } else if (source == OTNetworkDegradationSourceRemote) {
        NSLog(@"Remote publisher network is degraded (condition: %ld)", (long)remoteCondition);
    } else if (source == OTNetworkDegradationSourceBothOrUnclear) {
        NSLog(@"Degradation source unclear — local: %ld, remote: %ld", (long)localCondition, (long)remoteCondition);
    }
}

Relatório de estatísticas da RTC

Para obter estatísticas de conexão entre pares de baixo nível do publisher, use o OTPublisherKit getRtcStatsReport: método. Isso fornece relatórios de estatísticas do RTC para o fluxo de mídia. Trata-se de uma operação assíncrona. Defina o OTPublisherKit rtcStatsReportDelegate propriedade e implementar o OTPublisherKitRtcStatsReportDelegate publisher:rtcStatsReport: método antes de chamar [OTPublisherKit getRtcStatsReport:]. Quando as estatísticas estiverem disponíveis, a implementação do OTPublisherKitRtcStatsReportDelegate publisher:rtcStatsReport: A mensagem é enviada. A mensagem inclui uma matriz de OTPublisherRtcStats objetos, que incluem uma propriedade chamada 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 dos assinantes, use o OTSubscriberKit 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. Defina o OTSubscriberKit rtcStatsReportDelegate propriedade e implementar o OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport: método antes de chamar [OTSubscriberKit getRtcStatsReport:]. Quando as estatísticas estiverem disponíveis, a implementação do OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport: A mensagem é enviada. A mensagem inclui um parâmetro jsonArrayOfReports.

Aplicativo de exemplo

O Exemplo de estatísticas do lado do remetente do SDK de vídeo da Vonage para iOS em Swift utiliza as estatísticas do remetente em um aplicativo móvel desenvolvido com o Client SDK do iOS.