Observabilité du client : Linux

Le SDK Video de Vonage expose des mesures détaillées de la qualité du flux par le biais d'une API de statistiques de haut niveau - recommandée pour la plupart des cas d'utilisation - qui fournit des statistiques audio, vidéo, réseau et côté expéditeur sous une forme unifiée et consciente de la session, qui reste stable lors des transitions de connexion entre pairs. Pour le débogage avancé, le SDK permet également d'accéder au rapport de statistiques WebRTC brut, qui reflète les données de connexion entre pairs non traitées.

Le SDK expose également des mesures de l'état du réseau qui fournissent une évaluation de haut niveau de la santé de la connexion pour les éditeurs et les abonnés. Ces mesures comprennent un score d'état du réseau, la raison de ce score et, pour les abonnés, une source de dégradation indiquant quel côté de la connexion est responsable des problèmes observés. Voir État du réseau et source de dégradation pour plus de détails.

API pour les statistiques sur les liens audio, vidéo et médias

Le SDK Linux vidéo de Vonage envoie des statistiques périodiques sur le réseau audio, vidéo et de liaison média pour les éditeurs et les abonnés. Ces statistiques comprennent le nombre de paquets, les débits binaires, les données relatives à la fréquence d'images, les mesures de pause et de gel, les informations sur les codecs et les mesures de réseau au niveau du transport, telles que l'estimation de la bande passante et l'évaluation de l'état du réseau.

Les statistiques sont fournies par l'intermédiaire de :

otc_publisher_callbacks - statistiques côté éditeur
otc_subscriber_callbacks - statistiques relatives aux abonnés

Pour les recevoir, activez le rappel approprié sur l'éditeur ou l'abonné.

Activation des statistiques pour les éditeurs

Utilisez les fonctions de rappel on_audio_stats() et on_video_stats() de la méthode otc_publisher_callbacks pour surveiller les statistiques du flux d'un éditeur. Pour enregistrer des méthodes de rappel pour des rapports périodiques de statistiques audio et vidéo pour un éditeur, définissez la propriété on_audio_stats() et on_video_stats() fonctions de rappel lors de l'initialisation du otc_publisher_callbacks structure à utiliser à utiliser par l'éditeur.

Enregistrer un otc_publisher_callbacks lors de la création de l'éditeur :

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;

Et mettre en œuvre les rappels :

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);
}

Ces fonctions de rappel sont appelées périodiquement pour fournir des statistiques audio et vidéo à l'éditeur. pour l'éditeur. Chaque fonction est transmise de la manière suivante un pointeur sur le fichier éditeur struct, un pointeur sur le données_utilisateur que vous avez défini pour l'éditeur, un tableau de statistiques et le nombre de statistiques dans le tableau. Le paramètre stats est défini par le paramètre otc_publisher_audio_stats et otc_publisher_video_stats structures. Pour un éditeur dans une session acheminée (qui utilise l'option OpenTok Routeur média), le tableau comprend un objet, définissant les statistiques pour le flux audio ou vidéo unique envoyé au routeur vidéo de Vonage. le flux audio ou vidéo unique envoyé au routeur vidéo de Vonage. Dans une session relayée, le tableau comprend un objet pour chaque abonné au flux publié. au flux publié.

Réception d'événements de qualité vidéo sur les éditeurs

Pour les événements de qualité vidéo de l'éditeur :

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);
}

Réception d'événements relatifs à l'état du réseau sur l'éditeur

Pour recevoir les événements de changement des conditions du réseau pour l'éditeur, définissez l'option on_network_condition_changed dans le fichier 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);
}

Enregistrez-le avec les autres rappels :

pub_callbacks.on_network_condition_changed = handle_publisher_network_condition;

Ce rappel est déclenché lorsqu'un changement significatif de l'état du réseau est détecté pour l'éditeur. Il inclut les statistiques actuelles de la liaison média avec les métriques de transport.

Activation des statistiques pour les abonnés

Utilisez les fonctions de rappel on_audio_stats() et on_video_stats() de la méthode otc_subscriber_callbacks pour surveiller les statistiques du flux d'un abonné.

Enregistrer un otc_subscriber_callbacks lors de la création de l'abonné :

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

Mettre en œuvre les rappels :

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);
}

Réception d'événements relatifs à la qualité vidéo sur les abonnés

Pour les événements de qualité vidéo de l'éditeur :

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);
}

Réception d'événements relatifs à l'état du réseau sur l'abonné

Pour recevoir les événements de modification des conditions du réseau pour l'abonné, définissez l'option on_network_condition_changed dans le fichier 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);
}

Enregistrez-le avec les autres rappels :

sub_callbacks.on_network_condition_changed = handle_subscriber_network_condition;

Ce rappel est déclenché lorsqu'un changement significatif de l'état du réseau est détecté pour l'abonné ou l'éditeur distant. Il inclut les statistiques actuelles de la liaison média avec les métriques de transport locales et distantes et la source de dégradation.

Statistiques Structures de données

Cette section décrit les structures et les champs fournis par l'API de statistiques audio et vidéo du SDK C. Bien que toutes les plateformes SDK vidéo exposent le même ensemble de statistiques, il peut y avoir des différences mineures dans la façon dont chaque plateforme structure ou nomme les champs individuels. Ces variations reflètent les conventions de conception des SDK spécifiques à chaque plateforme plutôt que des différences dans les mesures sous-jacentes.

Pour une explication indépendante de la plate-forme des statistiques disponibles et de ce qu'elles représentent, voir aperçu de l'observabilité du client.

`otc_transport_stats`

Représente les mesures partagées au niveau du transport.

connection_estimated_bandwidth - Estimation de la largeur de bande de connexion disponible (bps)
network_condition - Score de l'état actuel du réseau (OTC_NETWORK_CONDITION_UNKNOWN, OTC_NETWORK_CONDITION_CRITICAL, OTC_NETWORK_CONDITION_WARNING, OTC_NETWORK_CONDITION_FAIR, OTC_NETWORK_CONDITION_GOODou OTC_NETWORK_CONDITION_EXCELLENT)
network_condition_reason - Raison principale de l'impact sur l'état du réseau (OTC_NETWORK_REASON_NONE, OTC_NETWORK_REASON_UNKNOWN, OTC_NETWORK_REASON_BANDWIDTHou OTC_NETWORK_REASON_PACKET_LOSS)

`otc_publisher_video_stats`

Fournit des statistiques sur la piste vidéo d'un éditeur :

connection_id - Dans une session relayée, l'identifiant de connexion du client souscrivant au flux est indiqué.
subscriber_id - Dans une session relayée, l'identifiant de l'abonné du client souscrivant au flux est indiqué.
packets_lost - Estimation des paquets vidéo perdus
packets_sent - Paquets vidéo envoyés
bytes_sent - Octets vidéo envoyés
timestamp - Horodatage Unix en millisecondes
start_time - L'horodatage, en millisecondes depuis l'époque Unix, à partir duquel les totaux cumulés ont commencé à s'accumuler.
video_layers - Tableau de statistiques sur la couche vidéo (voir otc_publisher_video_layer_stats)

`otc_publisher_audio_stats`

Fournit des statistiques sur la piste audio d'un éditeur :

connection_id - Dans une session relayée, l'identifiant de connexion du client souscrivant au flux est indiqué.
subscriber_id - Dans une session relayée, l'ID de l'abonné
packets_lost - Estimation des paquets audio perdus
packets_sent - Paquets audio envoyés
bytes_sent - Octets audio envoyés
timestamp - Horodatage Unix en millisecondes
start_time - L'horodatage, en millisecondes depuis l'époque Unix, à partir duquel les totaux cumulés ont commencé à s'accumuler.

`otc_publisher_video_layer_stats`

Représente une couche simulcast ou SVC :

width - Largeur de la trame codée
height - Hauteur du cadre codé
encoded_frame_rate - Encodé fps
bitrate - Débit de la couche (bps)
total_bitrate - Débit de la couche incluant le surdébit RTP (bps)
scalability_mode - Descripteur SVC/scalability (par exemple, "L3T3")
quality_limitation_reason - Raison de la limitation de la qualité (bande passante, CPU, codec, résolution ou changement de couche)
codec - Codec utilisé pour cette couche vidéo

`otc_subscriber_video_stats`

Fournit des statistiques sur la piste vidéo d'un abonné :

packets_lost - Estimation des paquets vidéo perdus
packets_received - Paquets vidéo reçus
bytes_received - Octets vidéo reçus
timestamp - Horodatage Unix en millisecondes
sender_connection_max_allocated_bitrate - Débit binaire maximal facultatif côté émetteur
sender_connection_estimated_bandwidth - Largeur de bande estimée du côté de l'expéditeur (en option)
width - Largeur de l'image décodée en pixels
height - Hauteur de l'image décodée en pixels
decoded_frame_rate - Images décodées par seconde
bitrate - Débit binaire vidéo (bps)
total_bitrate - Débit binaire incluant l'overhead RTP (bps)
pause_count - Nombre de pauses (>5s depuis la dernière image)
total_pauses_duration - Durée totale de la pause (ms)
freeze_count - Nombre de gels
total_freezes_duration - Durée totale de l'arrêt sur image (ms)
codec - Décodeur actuel codec

`otc_subscriber_audio_stats`

Fournit des statistiques sur la piste audio d'un abonné :

packets_lost - Estimation des paquets perdus
packets_received - Paquets reçus
bytes_received - Octets reçus
audio_level - Niveau audio (0-1.0)
timestamp - Horodatage Unix en millisecondes
sender_connection_max_allocated_bitrate - Débit binaire maximal facultatif côté émetteur
sender_connection_estimated_bandwidth - Largeur de bande estimée du côté de l'expéditeur (en option)
transport - Statistiques locales de transport et de réseau pour cet abonné (voir otc_transport_stats). Peut être limité si les statistiques côté expéditeur et/ou le repli audio sont désactivés.
remote_publisher_transport - Statistiques de transport et de réseau de l'éditeur à distance (voir otc_transport_stats). Peut être limité si les statistiques côté expéditeur et/ou le repli audio sont désactivés.

`otc_publisher_media_link_stats`

Fournit des statistiques au niveau du transport pour la connexion d'un éditeur.

transport - Statistiques de transport pour cet éditeur (voir otc_transport_stats)

`otc_subscriber_media_link_stats`

Fournit des statistiques au niveau du transport pour les connexions d'un abonné.

transport - Statistiques de transport pour la connexion descendante de cet abonné (voir otc_transport_stats)
remote_publisher_transport - Statistiques de transport pour la connexion ascendante de l'éditeur distant (voir otc_transport_stats). Peut être limité si les statistiques côté expéditeur ne sont pas activées.
network_degradation_source - Indique la source de la dégradation du réseau, le cas échéant (OTC_NETWORK_DEGRADATION_SOURCE_NONE, OTC_NETWORK_DEGRADATION_SOURCE_LOCAL, OTC_NETWORK_DEGRADATION_SOURCE_REMOTEou OTC_NETWORK_DEGRADATION_SOURCE_BOTH_OR_UNCLEAR)

Statistiques côté expéditeur

Voir le aperçu des statistiques côté expéditeur.

Activation des statistiques côté expéditeur

Les statistiques côté émetteur sont reçues par les abonnés. Pour recevoir les statistiques côté expéditeur, activez-les pour l'éditeur du flux en appelant otc_publisher_settings_set_sender_stats_track() avant de construire l'éditeur :

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

Si la piste de statistiques de l'expéditeur n'est pas activée, aucun canal de statistiques de l'expéditeur ne sera publié pour cet éditeur. La valeur par défaut est OTC_FALSE.

Réception des statistiques côté expéditeur

Si l'éditeur a activé les statistiques côté expéditeur, les abonnés les reçoivent automatiquement via les rappels de statistiques. décrite ci-dessus. Les otc_subscriber_video_stats et otc_subscriber_audio_stats comprennent deux champs côté émetteur :

sender_connection_max_allocated_bitrate - Le débit maximum qui peut être estimé pour la connexion
sender_connection_estimated_bandwidth - La largeur de bande actuelle estimée pour la connexion

Ces mesures sont calculées par groupe audio-vidéo, de sorte que les mêmes valeurs apparaissent dans les statistiques vidéo et audio.

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);
}

État et dégradation du réseau Source

Le SDK fournit des mesures de l'état du réseau en temps réel pour les éditeurs et les abonnés, y compris une note d'état, la raison de cette note et une source de dégradation pour les abonnés. Pour une explication complète du modèle d'état du réseau, des scores, des raisons et de la manière de l'activer, voir le document aperçu de l'observabilité du client.

Les données sur l'état du réseau sont disponibles par le biais de deux canaux :

Statistiques périodiques : Les transport Le champ "publisher" (éditeur) et "subscriber stats" (abonné) comprend les éléments suivants network_condition et network_condition_reason. Les statistiques sur les abonnés révèlent également remote_publisher_transport et network_degradation_source. Voir Structures statistiques pour plus de détails.
Événements liés à la modification de l'état du réseau : Des rappels dédiés sur les deux éditeur et abonné sont déclenchés lorsqu'un changement significatif de l'état du réseau est détecté.

L'exemple suivant montre comment utiliser les données sur l'état du réseau de l'abonné pour identifier la source de la dégradation :

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);
    }
}

Rapport statistique RTC

Pour obtenir des statistiques de bas niveau sur les connexions entre pairs pour un éditeur, utilisez la commande otc_publisher_get_rtc_stats_report() fonction. Elle fournit des rapports de statistiques RTC pour le flux média. Il s'agit d'une opération asynchrone. Créer un otc_publisher_rtc_stats_report_cb struct et de le passer dans le otc_publisher_set_rtc_stats_report_cb avant d'appeler la fonction otc_publisher_get_rtc_stats_report(). Lorsque les statistiques sont disponibles, le otc_publisher_rtc_stats_report_cb.on_rtc_stats_report() est appelée. Cette fonction comprend un stats qui est un pointeur sur un tableau de otc_publisher_rtc_stats structures. Cette structure comprend un json_array_of_reports propriété. Il s'agit d'un tableau JSON de rapports de statistiques RTC, qui sont similaires au format de l'objet RtcStatsReport mis en œuvre dans les navigateurs web (voir ces documents de Mozilla).

Pour obtenir des statistiques de bas niveau sur les connexions entre homologues pour un abonné, utilisez la commande otc_subscriber_get_rtc_stats_report() fonction. Elle fournit un rapport de statistiques RTC pour le flux média.

Il s'agit d'une opération asynchrone. Créer un otc_subscriber_rtc_stats_report_cb et la passer dans la structure otc_subscriber_set_rtc_stats_report_cb avant d'appeler la fonction otc_subscriber_get_rtc_stats_report(). Lorsque les statistiques sont disponibles, le otc_subscriber_rtc_stats_report_cb.on_rtc_stats_report est appelée.

Cette fonction de rappel comprend un json_array_of_reports paramètre. Il s'agit d'un tableau JSON de rapports de statistiques RTC, qui sont similaires au format de l'objet RtcStatsReport mis en œuvre dans les navigateurs web (voir ces documents de Mozilla).

Voir aussi cette documentation du W3C.

Navigation

Observabilité du client : Linux

API pour les statistiques sur les liens audio, vidéo et médias

Activation des statistiques pour les éditeurs

Réception d'événements de qualité vidéo sur les éditeurs

Réception d'événements relatifs à l'état du réseau sur l'éditeur

Activation des statistiques pour les abonnés

Réception d'événements relatifs à la qualité vidéo sur les abonnés

Réception d'événements relatifs à l'état du réseau sur l'abonné

Statistiques Structures de données

otc_transport_stats

otc_publisher_video_stats

otc_publisher_audio_stats

otc_publisher_video_layer_stats

otc_subscriber_video_stats

otc_subscriber_audio_stats

otc_publisher_media_link_stats

otc_subscriber_media_link_stats

Statistiques côté expéditeur

Activation des statistiques côté expéditeur

Réception des statistiques côté expéditeur

État et dégradation du réseau Source

Rapport statistique RTC