Observabilidade do cliente: Linux

O SDK de vídeo da Vonage 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 bruto de estatísticas 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.

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

O SDK do Vonage Video para Linux envia estatísticas periódicas de rede relacionadas a áudio, vídeo e links de mídia, tanto para emissores quanto para 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:

• otc_publisher_callbacks — estatísticas do lado do editor

• otc_subscriber_callbacks — estatísticas do lado do assinante

Para recebê-las, habilite o callback apropriado no editor ou no assinante.

Ativação das estatísticas para editores

Utilize as funções de retorno de chamada on_audio_stats() e on_video_stats() do otc_publisher_callbacks para monitorar as estatísticas do stream de um editor. Para registrar métodos de retorno de chamada para relatórios periódicos de estatísticas de áudio e vídeo de um editor, defina o on_audio_stats() e on_video_stats() funções de retorno de chamada ao inicializar o otc_publisher_callbacks estrutura a ser utilizada pela editora.

Registrar um otc_publisher_callbacks estrutura ao criar o editor:

struct otc_publisher_callbacks pub_callbacks;
pub_callbacks.on_audio_stats = handle_publisher_audio_stats;
pub_callbacks.on_video_stats = handle_publisher_video_stats;
pub_callbacks.on_video_quality_changed = handle_publisher_quality_change;
pub_callbacks.on_media_link_stats = handle_publisher_media_link_stats;

E implementar os callbacks:

void handle_publisher_audio_stats(otc_publisher* publisher,
                                  void* user_data,
                                  struct otc_publisher_audio_stats audio_stats[],
                                  size_t number_of_stats) {
    printf("Audio bytes sent: %lld\n", (long long)audio_stats[0].bytes_sent);
}

void handle_publisher_video_stats(otc_publisher* publisher,
                                  void* user_data,
                                  struct otc_publisher_video_stats video_stats[],
                                  size_t number_of_stats) {
    printf("Video packets sent: %lld\n", (long long)video_stats[0].packets_sent);
}

void handle_publisher_media_link_stats(otc_publisher* publisher,
                                        void* user_data,
                                        struct otc_publisher_media_link_stats media_link_stats[],
                                        size_t number_of_stats) {
    printf("Publisher uplink bandwidth: %lld bps\n", (long long)media_link_stats[0].transport.connection_estimated_bandwidth);
    printf("Network condition: %d\n", (int)media_link_stats[0].transport.network_condition);
    printf("Condition reason: %d\n", (int)media_link_stats[0].transport.network_condition_reason);
}

Essas funções de retorno de chamada são chamadas periodicamente para relatar estatísticas de áudio e vídeo para o editor. Cada função recebe os seguintes parâmetros: um ponteiro para o editora struct, um ponteiro para o dados_do_usuário que você define para o editor, um array de estatísticas e o número de estatísticas no array. O parâmetro “stats” é definido pelo otc_publisher_audio_stats e otc_publisher_video_stats estruturas. Para um editor em uma sessão roteada (aquela que utiliza o OpenTok Roteador de mídia), 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

Para eventos relacionados à qualidade de vídeo dos editores:

void handle_publisher_quality_change(otc_publisher* publisher,
                                     void* user_data,
                                     const struct otc_publisher_video_stats* stats,
                                     enum otc_video_reason reason) {
    printf("Publisher video quality event: %d\n", reason);
}

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

Para receber eventos de alteração nas condições da rede para o editor, defina o on_network_condition_changed função de retorno na otc_publisher_callbacks struct:

void handle_publisher_network_condition(otc_publisher* publisher,
                                        void* user_data,
                                        const struct otc_publisher_media_link_stats* media_link_stats,
                                        enum otc_network_reason reason) {
    printf("Publisher network condition: %d\n", (int)media_link_stats->transport.network_condition);
    printf("Reason: %d\n", (int)media_link_stats->transport.network_condition_reason);
}

Registre-o junto com os outros callbacks:

pub_callbacks.on_network_condition_changed = handle_publisher_network_condition;

Essa função de retorno é acionada quando é detectada uma mudança 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.

Ativação de estatísticas para assinantes

Utilize as funções de retorno de chamada on_audio_stats() e on_video_stats() do otc_subscriber_callbacks para monitorar as estatísticas do stream de um assinante.

Registrar um otc_subscriber_callbacks estrutura ao criar o assinante:

struct otc_subscriber_callbacks sub_callbacks;
sub_callbacks.on_audio_stats = handle_subscriber_audio_stats;
sub_callbacks.on_video_stats = handle_subscriber_video_stats;
sub_callbacks.on_video_quality_changed = handle_subscriber_quality_change;
sub_callbacks.on_media_link_stats = handle_subscriber_media_link_stats;

otc_subscriber* subscriber = otc_subscriber_new(stream, sub_callbacks, user_data);

Implemente os callbacks:

void handle_subscriber_audio_stats(otc_subscriber* subscriber,
                                   void* user_data,
                                   struct otc_subscriber_audio_stats audio_stats) {
    printf("Audio packets received: %llu\n", audio_stats.packets_received);
}

void handle_subscriber_video_stats(otc_subscriber* subscriber,
                                   void* user_data,
                                   struct otc_subscriber_video_stats video_stats) {
    printf("Video bytes received: %llu\n", video_stats.bytes_received);
}

void handle_subscriber_media_link_stats(otc_subscriber* subscriber,
                                          void* user_data,
                                          const struct otc_subscriber_media_link_stats* media_link_stats,
                                          size_t number_of_stats) {
    printf("Local downlink bandwidth: %lld bps\n", (long long)media_link_stats->transport.connection_estimated_bandwidth);
    printf("Remote publisher uplink bandwidth: %lld bps\n", (long long)media_link_stats->remote_publisher_transport.connection_estimated_bandwidth);
    printf("Degradation source: %d\n", (int)media_link_stats->network_degradation_source);
}

Recebimento de eventos de qualidade de vídeo nos assinantes

Para eventos relacionados à qualidade de vídeo dos editores:

void handle_subscriber_quality_change(otc_subscriber* subscriber,
                                      void* user_data,
                                      const struct otc_subscriber_video_stats* stats,
                                      enum otc_video_reason reason) {
    printf("Subscriber video quality event: %d\n", 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, defina o on_network_condition_changed função de retorno na otc_subscriber_callbacks struct:

void handle_subscriber_network_condition(otc_subscriber* subscriber,
                                          void* user_data,
                                          const struct otc_subscriber_media_link_stats* media_link_stats,
                                          enum otc_network_reason reason) {
    printf("Local network condition: %d\n", (int)media_link_stats->transport.network_condition);
    printf("Remote publisher network condition: %d\n", (int)media_link_stats->remote_publisher_transport.network_condition);
    printf("Degradation source: %d\n", (int)media_link_stats->network_degradation_source);
}

Registre-o junto com os outros callbacks:

sub_callbacks.on_network_condition_changed = handle_subscriber_network_condition;

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.

Estatística e Estruturas de Dados

Esta seção descreve as estruturas e os campos fornecidos pela API de estatísticas de áudio e vídeo do SDK C. 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.

otc_transport_stats

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

• connection_estimated_bandwidth — Largura de banda estimada disponível da conexão (bps)
• network_condition — Pontuação atual do estado da rede (OTC_NETWORK_CONDITION_UNKNOWN, OTC_NETWORK_CONDITION_CRITICAL, OTC_NETWORK_CONDITION_WARNING, OTC_NETWORK_CONDITION_FAIR, OTC_NETWORK_CONDITION_GOOD, ou OTC_NETWORK_CONDITION_EXCELLENT)
• network_condition_reason — Principal motivo que afeta o estado da rede (OTC_NETWORK_REASON_NONE, OTC_NETWORK_REASON_UNKNOWN, OTC_NETWORK_REASON_BANDWIDTH, ou OTC_NETWORK_REASON_PACKET_LOSS)

otc_publisher_video_stats

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

• connection_id — Em uma sessão retransmitida, o ID de conexão do cliente que está assinando o fluxo
• subscriber_id — Em uma sessão retransmitida, o ID do assinante do cliente que está assinando o fluxo
• packets_lost — Estimativa de pacotes de vídeo perdidos
• packets_sent — Pacotes de vídeo enviados
• bytes_sent — Bytes de vídeo enviados
• timestamp — Carimbo de data/hora do Unix em milissegundos
• start_time — O carimbo de data e hora, em milissegundos desde a época Unix, a partir do qual os totais acumulados começaram a ser calculados
• video_layers — Matriz de estatísticas da camada de vídeo (consulte otc_publisher_video_layer_stats)

otc_publisher_audio_stats

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

• connection_id — Em uma sessão retransmitida, o ID de conexão do cliente que está assinando o fluxo
• subscriber_id — Em uma sessão retransmitida, o ID do assinante
• packets_lost — Estimativa de pacotes de áudio perdidos
• packets_sent — Pacotes de áudio enviados
• bytes_sent — Trechos de áudio enviados
• timestamp — Carimbo de data/hora do Unix em milissegundos
• start_time — O carimbo de data e hora, em milissegundos desde a época Unix, a partir do qual os totais acumulados começaram a ser calculados

otc_publisher_video_layer_stats

Representa uma transmissão simultânea ou uma camada SVC:

• width — Largura do quadro codificado
• height — Altura do quadro codificado
• encoded_frame_rate — fps codificados
• bitrate — Taxa de bits da camada (bps)
• total_bitrate — Taxa de bits da camada, incluindo a sobrecarga do RTP (bps)
• scalability_mode — Descritor SVC/escalabilidade (por exemplo, “L3T3”)
• quality_limitation_reason — Motivo da limitação de qualidade (largura de banda, CPU, codec, resolução ou mudança de camada)
• codec — Codec utilizado nesta camada de vídeo

otc_subscriber_video_stats

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

• packets_lost — Estimativa de pacotes de vídeo perdidos
• packets_received — Pacotes de vídeo recebidos
• bytes_received — Bytes de vídeo recebidos
• timestamp — Carimbo de data/hora do Unix em milissegundos
• sender_connection_max_allocated_bitrate — Taxa de bits máxima opcional do lado do remetente
• sender_connection_estimated_bandwidth — Largura de banda estimada opcional do lado do remetente
• width — Largura do quadro decodificado em pixels
• height — Altura do quadro decodificado em pixels
• decoded_frame_rate — Quadros por segundo decodificados
• bitrate — Taxa de bits do vídeo (bps)
• total_bitrate — Taxa de bits, incluindo a sobrecarga do RTP (bps)
• pause_count — Número de pausas (mais de 5 s desde o último quadro)
• total_pauses_duration — Duração total da pausa (ms)
• freeze_count — Número de travamentos
• total_freezes_duration — Duração total do congelamento (ms)
• codec — Codec atual do decodificador

otc_subscriber_audio_stats

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

• packets_lost — Estimativa de pacotes perdidos
• packets_received — Pacotes recebidos
• bytes_received — Bytes recebidos
• audio_level — Nível de áudio (0–1,0)
• timestamp — Carimbo de data/hora do Unix em milissegundos
• sender_connection_max_allocated_bitrate — Taxa de bits máxima opcional do lado do remetente
• sender_connection_estimated_bandwidth — Largura de banda estimada opcional do lado do remetente
• transport — Estatísticas de transporte local e de rede para este assinante (consulte otc_transport_stats). Pode ser limitado se as estatísticas do remetente e/ou o recurso alternativo de áudio estiverem desativados.
• remote_publisher_transport — Estatísticas de transporte e de rede do editor remoto (consulte otc_transport_stats). Pode ser limitado se as estatísticas do remetente e/ou o recurso alternativo de áudio estiverem desativados.

otc_publisher_media_link_stats

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 otc_transport_stats)

otc_subscriber_media_link_stats

Fornece estatísticas no nível de transporte para as conexões de um assinante.

• transport — Estatísticas de transporte para a conexão de downlink deste assinante (consulte otc_transport_stats)
• remote_publisher_transport — Estatísticas de transporte para a conexão de uplink do editor remoto (consulte otc_transport_stats). Pode ser limitado se as estatísticas do remetente não estiverem ativadas.
• network_degradation_source — Indica a origem da degradação da rede, se houver (OTC_NETWORK_DEGRADATION_SOURCE_NONE, OTC_NETWORK_DEGRADATION_SOURCE_LOCAL, OTC_NETWORK_DEGRADATION_SOURCE_REMOTE, ou OTC_NETWORK_DEGRADATION_SOURCE_BOTH_OR_UNCLEAR)

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 chamando otc_publisher_settings_set_sender_stats_track() função antes de criar o publisher:

otc_publisher_settings* settings = otc_publisher_settings_new();
otc_publisher_settings_set_sender_stats_track(settings, OTC_TRUE);

otc_publisher* publisher = otc_publisher_new_with_settings( &publisher_callbacks, settings);

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

Recebimento de estatísticas do lado do remetente

Se o editor tiver ativado as estatísticas do remetente, os assinantes as recebem automaticamente por meio dos callbacks de estatísticas descrito acima. O otc_subscriber_video_stats e otc_subscriber_audio_stats As estruturas incluem dois campos do lado do remetente:

• sender_connection_max_allocated_bitrate — A taxa de bits máxima que pode ser estimada para a conexão
• sender_connection_estimated_bandwidth — 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 handle_subscriber_video_stats(otc_subscriber* subscriber,
                                   void* user_data,
                                   struct otc_subscriber_video_stats stats) {
    printf("Connection max allocated bitrate: %lld bps\n", (long long)stats.sender_connection_max_allocated_bitrate);
    printf("Connection estimated bandwidth: %lld bps\n", (long long)stats.sender_connection_estimated_bandwidth);
}

Condição da rede e fonte da 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: O transport O campo nas estruturas de estatísticas do editor e do assinante inclui network_condition e network_condition_reason. As estatísticas dos assinantes também revelam remote_publisher_transport e network_degradation_source. Veja Estruturas estatísticas para mais detalhes.
• Eventos relacionados a alterações nas condições da rede: Callbacks dedicados em ambos editora e 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 handle_subscriber_network_condition(otc_subscriber* subscriber,
                                          void* user_data,
                                          const struct otc_subscriber_video_stats* video_stats,
                                          const struct otc_subscriber_audio_stats* audio_stats,
                                          enum otc_network_reason reason) {
    enum otc_network_condition local_condition = video_stats->transport.network_condition;
    enum otc_network_condition remote_condition = video_stats->remote_publisher_transport.network_condition;
    enum otc_network_degradation_source source = video_stats->network_degradation_source;

    if (source == OTC_NETWORK_DEGRADATION_SOURCE_LOCAL) {
        printf("Local network is degraded (condition: %d)\n", (int)local_condition);
    } else if (source == OTC_NETWORK_DEGRADATION_SOURCE_REMOTE) {
        printf("Remote publisher network is degraded (condition: %d)\n", (int)remote_condition);
    } else if (source == OTC_NETWORK_DEGRADATION_SOURCE_BOTH_OR_UNCLEAR) {
        printf("Degradation source unclear — local: %d, remote: %d\n", (int)local_condition, (int)remote_condition);
    }
}

Relatório de Estatísticas da RTC

Para obter estatísticas de conexão entre pares de baixo nível para um editor, use o otc_publisher_get_rtc_stats_report() função. Ela fornece relatórios de estatísticas de RTC para o fluxo de mídia. Trata-se de uma operação assíncrona. Crie um otc_publisher_rtc_stats_report_cb struct e passá-lo para o otc_publisher_set_rtc_stats_report_cb função antes de chamar otc_publisher_get_rtc_stats_report(). Quando as estatísticas estiverem disponíveis, o otc_publisher_rtc_stats_report_cb.on_rtc_stats_report() a função de retorno de chamada é chamada. Essa função inclui um stats parâmetro, que é um ponteiro para uma matriz de otc_publisher_rtc_stats estruturas. Essa estrutura inclui um json_array_of_reports propriedade. 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).

Para obter estatísticas de conexão entre pares de baixo nível para um assinante, ou para obter estatísticas mais detalhadas sobre o fluxo, use o otc_subscriber_get_rtc_stats_report() função. Ela fornece um relatório de estatísticas do RTC para o fluxo de mídia.

Esta é uma operação assíncrona. Crie um otc_subscriber_rtc_stats_report_cb struct e passá-la para o otc_subscriber_set_rtc_stats_report_cb função antes de chamar otc_subscriber_get_rtc_stats_report(). Quando as estatísticas estiverem disponíveis, o otc_subscriber_rtc_stats_report_cb.on_rtc_stats_report a função de retorno de chamada é chamada.

Essa função de retorno de chamada inclui um json_array_of_reports parâmetro. 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.