Observabilité des clients — Windows

• Vue d'ensemble
• Web
• iOS
• iOS (Swift)
• Android
• Fenêtres
• Linux
• React Native

Le SDK OpenTok pour Windows 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 Windows d'OpenTok transmet 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 le biais des événements suivants :

• Publisher.AudioStatsUpdated - statistiques audio côté éditeur
• Publisher.VideoStatsUpdated - statistiques vidéo côté éditeur
• Publisher.MediaLinkStatsUpdated - statistiques sur les liens médias côté éditeur (métriques de transport)
• Publisher.VideoQualityChanged - notification de changement de qualité vidéo de l'éditeur
• Publisher.NetworkConditionChanged - notification de modification des conditions du réseau de l'éditeur
• Subscriber.AudioStatsUpdated - statistiques audio côté abonné
• Subscriber.VideoStatsUpdated - statistiques vidéo côté abonné
• Subscriber.MediaLinkStatsUpdated - statistiques sur les liens médias du côté de l'abonné (métriques de transport)
• Subscriber.VideoQualityChanged - notification de changement de qualité vidéo de l'abonné
• Subscriber.NetworkConditionChanged - notification de modification de l'état du réseau de l'abonné

Pour les recevoir, définissez le gestionnaire d'événement approprié sur l'éditeur ou l'abonné.

Activation des statistiques pour les éditeurs

Définir les gestionnaires d'événements correspondants pour Publisher.AudioStatsUpdated et 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}");
    }
};

Ces événements sont envoyés périodiquement pour fournir des statistiques audio et vidéo à l'éditeur. Les gestionnaires d'événements sont transmis sous la forme d'un tableau d'événements AudioNetworkStats et VideoNetworkStats Chaque méthode reçoit deux objets : l'éditeur et un tableau d'objets stats . Pour un éditeur dans une session routée (qui utilise la méthode 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

Si vous êtes également intéressé par les événements relatifs à la qualité vidéo, mettez en œuvre ce gestionnaire :

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

Réception d'événements signalant un changement d'état du réseau au niveau des éditeurs

Pour recevoir les événements de modification des conditions du réseau pour l'éditeur, abonnez-vous à la fonction Publisher.NetworkConditionChanged événement :

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

Cet événement est déclenché lorsqu'un changement significatif de l'état du réseau est détecté chez l'éditeur. Il comprend les statistiques actuelles de la liaison multimédia, ainsi que les indicateurs de transport.

Activation des statistiques pour les abonnés

Définir les gestionnaires d'événements correspondants pour Subscriber.AudioStatsUpdated et 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}");
};

Réception d'événements liés à la qualité vidéo chez les abonnés

Si vous êtes également intéressé par les événements relatifs à la qualité vidéo, mettez en œuvre ce gestionnaire :

subscriber.VideoQualityChanged += (sender, args) =>
{
    Console.WriteLine($"Subscriber video quality event: {args.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 de l'état du réseau pour l'abonné, souscrivez à l'option Subscriber.NetworkConditionChanged événement :

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

Cet événement est déclenché lorsqu'un changement significatif de l'état du réseau est détecté chez l'abonné ou l'éditeur distant. Il comprend les statistiques actuelles de la liaison multimédia, ainsi que les indicateurs de transport locaux et distants et la source de la dégradation.

Structures de données statistiques

Cette section présente les structures et les champs fournis par l'API de statistiques audio et vidéo du Windows Video SDK. Bien que toutes les plates-formes SDK vidéo exposent le même ensemble de statistiques, il peut y avoir des différences mineures dans la façon dont chaque plate-forme 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.

TransportStats

Représente les mesures au niveau du transport.

• ConnectionEstimatedBandwidth - Estimation de la largeur de bande de connexion disponible (bps)
• Condition - Score de l'état actuel du réseau (NetworkCondition.Unknown, NetworkCondition.Critical, NetworkCondition.Warning, NetworkCondition.Fair, NetworkCondition.Goodou NetworkCondition.Excellent)
• NetworkConditionReason - Raison principale de l'impact sur l'état du réseau (NetworkReason.None, NetworkReason.Unknown, NetworkReason.Bandwidthou NetworkReason.PacketLoss)

Publisher.AudioNetworkStats

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

• ConnectionId - ID de connexion de l'abonné (relayé uniquement)
• SubscriberId - ID de l'abonné (relayé uniquement)
• PacketsLost - Total des paquets audio perdus
• PacketsSent - Total des paquets audio envoyés
• BytesSent - Nombre total d'octets audio envoyés
• Timestamp - Date à laquelle les statistiques ont été recueillies (ms)
• StartTime - Horodatage du début des totaux cumulés (ms)

Publisher.VideoNetworkStats

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

• ConnectionId - ID de connexion de l'abonné (relayé uniquement)
• SubscriberId - ID de l'abonné (relayé uniquement)
• PacketsLost - Paquets vidéo perdus
• PacketsSent - Paquets vidéo envoyés
• BytesSent - Octets vidéo envoyés
• Timestamp - Date à laquelle les statistiques ont été recueillies
• StartTime - Date à laquelle les totaux cumulés ont commencé
• VideoLayers - Liste des couches simulcast/SVC (VideoLayerStats)

Publisher.VideoLayerStats

Représente une seule couche vidéo simulcast ou SVC.

• Width - Largeur de la trame codée
• Height - Hauteur du cadre codé
• EncodedFrameRate - Images codées par seconde
• Bitrate - Débit de la couche (bps)
• TotalBitrate - Débit binaire incluant l'overhead RTP (bps)
• ScalabilityMode - Description du SVC/de l'évolutivité (par exemple, "L3T3")
• QualityLimitationReason - Raison de la réduction de la qualité
• Codec - Codec utilisé pour cette couche

Publisher.PublisherMediaLinkStats

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

• Transport - Statistiques de transport pour cet éditeur (voir TransportStats)

Subscriber.AudioNetworkStatsEventArgs

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

• PacketsLost - Estimation des paquets audio perdus
• PacketsReceived - Paquets audio reçus
• BytesReceived - Octets audio reçus
• Timestamp - Date à laquelle les statistiques ont été recueillies
• SenderStats - Estimation du réseau du côté de l'expéditeur (facultatif)

Subscriber.VideoNetworkStatsEventArgs

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

• PacketsLost - Paquets vidéo perdus
• PacketsReceived - Paquets vidéo reçus
• BytesReceived - Octets vidéo reçus
• Timestamp - Date à laquelle les statistiques ont été recueillies
• SenderStats - Estimation du réseau du côté de l'expéditeur (facultatif)
• Width - Largeur de la trame décodée
• Height - Hauteur du cadre décodé
• DecodedFrameRate - Images décodées par seconde
• Bitrate - Débit binaire vidéo (bps)
• TotalBitrate - Débit binaire total, y compris le surdébit RTP
• PauseCount - Nombre de pauses vidéo (>5s sans image)
• TotalPausesDuration - Durée totale de la pause (ms)
• FreezeCount - Nombre de gels définis par WebRTC
• TotalFreezesDuration - Durée totale de l'arrêt sur image (ms)
• Codec - Décodeur codec

Subscriber.SubscriberMediaLinkStats

Fournit des statistiques au niveau du transport pour les connexions d'un abonné, y compris une visibilité sur les performances du réseau de l'éditeur distant. Cela permet aux Applications de diagnostiquer si les problèmes de connexion proviennent de la liaison descendante de l'abonné ou de la liaison montante de l'éditeur.

• Transport - Statistiques de transport pour la connexion descendante de cet abonné (voir TransportStats)
• RemotePublisherTransport - Statistiques de transport pour la connexion ascendante de l'éditeur distant (voir TransportStats). Peut être limité si les statistiques côté expéditeur ne sont pas activées.
• NetworkDegradationSource - Indique la source de la dégradation du réseau, le cas échéant (NetworkDegradationSource.None, NetworkDegradationSource.Local, NetworkDegradationSource.Remoteou NetworkDegradationSource.BothOrUnclear)

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é émetteur, il faut les activer pour l'éditeur du flux en définissant l'attribut HasSenderStatsTrack à la propriété true lors de la construction de l'éditeur :

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

Publisher publisher = publisherBuilder.Build();

Si HasSenderStatsTrack n'est pas activé, aucun canal de statistiques sur les expéditeurs ne sera publié pour cet éditeur. La valeur par défaut est 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 par l'intermédiaire de l'option VideoStatsUpdated et AudioStatsUpdated événements décrite ci-dessus. Les SenderStats sur les deux VideoNetworkStatsEventArgs et AudioNetworkStatsEventArgs fournit deux mesures :

• ConnectionMaxAllocatedBitrate - Le débit maximum qui peut être estimé pour la connexion
• ConnectionEstimatedBandwidth - 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.

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

É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 Condition et NetworkConditionReason. Pour les abonnés, les statistiques sur les liens avec les médias comprennent également RemotePublisherTransport et NetworkDegradationSource.
• Événements liés à la modification de l'état du réseau : Des événements spécifiques, tant du côté de l'éditeur que de celui de l'abonné, sont déclenchés lorsqu'un changement significatif des conditions 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 :

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

Rapport statistique RTC

Utilisez l'API RTC Stats pour obtenir des données de diagnostic au niveau WebRTC. Pour obtenir les statistiques de connexion entre pairs de bas niveau d'un éditeur, utilisez la Publisher.GetRtcStatsReport() méthode. Elle fournit des rapports statistiques RTC pour le flux multimédia. Il s'agit d'une opération asynchrone. Lorsque les statistiques sont disponibles, l'événement RtcStatsReport est déclenché. L'objet RtcStatsReportArgs contient un tableau de Éditeur RtcStats objets, qui comprennent une propriété `JsonArrayOfReports`. 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 les statistiques de connexion entre pairs de bas niveau d'un abonné, utilisez la commande Subscriber.GetRtcStatsReport() méthode. Celle-ci fournit un rapport statistique RTC pour le flux multimédia. Il s'agit d'une opération asynchrone. Lorsque les statistiques sont disponibles, l'événement RtcStatsReport est déclenché. RtcStatsReportArgs L'objet comprend une propriété JsonArrayOfReports. 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.

Demande d'un rapport de statistiques RTC pour un éditeur :

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

publisher.GetRtcStatsReport();