Observabilité côté client — Linux

Le SDK OpenTok pour Linux propose des appels permettant d'accéder aux statistiques réseau et multimédia en temps réel au cours d'une session vidéo. Ces appels fournissent des indicateurs détaillés sur la qualité du flux — tels que la perte de paquets, les données reçues et la bande passante — et peuvent être utilisés sur n'importe quel flux émetteur ou abonné.

Le SDK vidéo OpenTok fournit des indicateurs détaillés sur la qualité du flux via une API de statistiques de haut niveau — recommandée pour la plupart des cas d’utilisation — qui propose des statistiques audio, vidéo, réseau et côté émetteur sous une forme unifiée et adaptée à la session, qui reste stable lors des transitions entre connexions entre pairs. Pour un débogage avancé, le SDK offre également l'accès au rapport brut des statistiques WebRTC, qui reflète les données brutes relatives aux connexions entre pairs.

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.

Ce guide comprend les sections suivantes :

API de statistiques sur les liens audio, vidéo et multimédia
Structures statistiques
Statistiques côté expéditeur
État du réseau et source de dégradation
Rapport statistique RTC

API de statistiques sur les liens audio, vidéo et multimédia

Le SDK OpenTok pour Linux envoie périodiquement des statistiques relatives à l'audio, à la vidéo et aux liens multimédias, tant pour les émetteurs que pour les abonnés. Ces statistiques comprennent le nombre de paquets, les débits binaires, les données relatives à la fréquence d'images, les indicateurs de pause/gel, les informations sur les codecs, ainsi que des indicateurs réseau au niveau du transport, tels 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 lorsque vous initialisez la structure `otc_publisher_callbacks` destinée à être utilisée 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 communiquer des statistiques audio et vidéo à l'éditeur. Chaque fonction reçoit les paramètres suivants : un pointeur vers la structure de l'éditeur, un pointeur vers les données utilisateur (user_data) que vous avez définies pour l'éditeur, un tableau de statistiques et le nombre de statistiques contenues dans ce tableau. Le paramètre « stats » est défini par le otc_publisher_audio_stats et otc_publisher_video_stats structures. Pour un éditeur dans une session routée (c'est-à-dire une session qui utilise le Routeur multimédia OpenTok, le tableau contient un objet définissant les statistiques relatives au flux multimédia audio ou vidéo unique envoyé au routeur multimédia vidéo Vonage. Dans une session relayée, le tableau contient un objet pour chaque abonné au flux publié.

Réception d'événements liés à la qualité vidéo chez 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 signalant un changement d'é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) {
    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 liés à la qualité vidéo chez 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 liés à la modification de l'état du réseau chez 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.

Structures de données statistiques

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)
transport - Statistiques de transport pour cet éditeur

`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.
transport - Statistiques de transport pour cet éditeur

`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_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 du réseau et source de dégradation

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 événements liés aux statistiques des médias comprennent des mesures de transport avec network_condition et network_condition_reason. Pour les abonnés, les statistiques sur les liens avec les médias comprennent également remote_publisher_transport et network_degradation_source. Voir Statistiques relatives aux liens vers les médias des éditeurs et Statistiques relatives aux liens partagés par les abonnés 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_media_link_stats* media_link_stats,
                                          enum otc_network_reason reason) {
    enum otc_network_condition local_condition = media_link_stats->transport.network_condition;
    enum otc_network_condition remote_condition = media_link_stats->remote_publisher_transport.network_condition;
    enum otc_network_degradation_source source = media_link_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 statistiques RTC pour le flux multimédia. Il s'agit d'une opération asynchrone. Créez un otc_publisher_rtc_stats_report_cb struct et la transmettre à la otc_publisher_set_rtc_stats_report_cb avant d'appeler la fonction `otc_publisher_get_rtc_stats_report()`. Lorsque les statistiques sont disponibles, la fonction de rappel `otc_publisher_rtc_stats_report_cb.on_rtc_stats_report()` est appelée. Cette fonction reçoit un paramètre stats, qui est un pointeur vers un tableau de otc_publisher_rtc_stats structures. Cette structure comprend une propriété « json_array_of_reports ». Il s'agit d'un tableau JSON contenant des rapports de statistiques RTC, dont le format est similaire à celui de l'objet RtcStatsReport implémenté dans les navigateurs Web (voir ces documents de Mozilla. Voir aussi cette documentation du W3C.

Pour obtenir des statistiques de bas niveau sur les connexions entre pairs pour un abonné, utilisez la commande otc_subscriber_get_rtc_stats_report() fonction. Celle-ci fournit un rapport statistique RTC pour le flux multimédia. Il s'agit d'une opération asynchrone. Créez un otc_subscriber_rtc_stats_report_cb struct et la transmettre à la otc_subscriber_set_rtc_stats_report_cb fonction avant d'appeler otc_subscriber_get_rtc_stats_report(). Lorsque les statistiques sont disponibles, otc_subscriber_rtc_stats_report_cb.on_rtc_stats_report La fonction de rappel est appelée. Cette fonction de rappel reçoit un paramètre `json_array_of_reports`. Il s'agit d'un tableau JSON contenant des rapports de statistiques RTC, dont le format est similaire à celui de l'objet `RtcStatsReport` implémenté dans les navigateurs Web (voir ces documents de Mozilla. Voir aussi cette documentation du W3C.