Observabilité du client : iOS

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 iOS vidéo de Vonage envoie des statistiques périodiques sur l'audio, la vidéo et les liens multimédias pour les éditeurs et les abonnés. Ces statistiques comprennent le nombre de paquets, les débits binaires, les données sur 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 :

OTPublisherKitNetworkStatsDelegate - statistiques côté éditeur (audio, vidéo)
OTSubscriberKitNetworkStatsDelegate - statistiques relatives aux abonnés (audio, vidéo)

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

Activation des statistiques pour les éditeurs

Attachez une classe qui adopte OTPublisherKitNetworkStatsDelegate :

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

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

Mettre en œuvre les rappels :

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

Pour un éditeur dans une session acheminée (qui utilise l'option Routeur vidéo multimédia de Vonage), le tableau stats comprend un objet, définissant les statistiques pour le flux audio ou vidéo unique envoyé au routeur vidéo de Vonage. Dans une session relayée, le tableau de statistiques comprend un objet pour chaque abonné au flux publié. le flux publié.

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

Si vous êtes également intéressé par les événements relatifs à la qualité de la vidéo, implémentez ce callback :

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

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

Réception des événements relatifs aux conditions du réseau sur les éditeurs

Pour recevoir les événements de modification des conditions du réseau pour l'éditeur, implémentez la fonction publisher:networkConditionChanged:mediaLinkStats:reason: rappel :

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

Ce rappel est déclenché lorsqu'un changement significatif de l'état du réseau est détecté pour l'éditeur. Elle inclut les statistiques de la liaison média en cours avec les métriques de transport. Voir État du réseau et source de dégradation pour plus de détails sur l'interprétation des notes et des raisons de l'état du réseau.

Activation des statistiques pour les abonnés

Joindre une classe qui adopte OTSubscriberKitNetworkStatsDelegate:

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

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

Mettre en œuvre les rappels :

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

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

En outre, gérer les événements de modification de la qualité vidéo de l'abonné :

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

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

Réception des événements relatifs à l'état du réseau sur les abonnés

Pour recevoir les événements de changement d'état du réseau pour l'abonné, mettez en œuvre la fonction subscriber:networkConditionChanged:mediaLinkStats:reason: rappel :

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

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. Voir État du réseau et source de dégradation pour plus de détails sur l'interprétation des notes et des raisons de l'état du réseau.

Statistiques Structures de données

Cette section présente les structures et les propriétés fournies par l'API de statistiques audio et vidéo d'iOS. 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.

`OTTransportStats`

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

connectionEstimatedBandwidth - Estimation de la largeur de bande de connexion disponible (bps).
networkCondition - Score de l'état actuel du réseau (OTNetworkConditionUnknown, OTNetworkConditionCritical, OTNetworkConditionWarning, OTNetworkConditionFair, OTNetworkConditionGoodou OTNetworkConditionExcellent).
networkConditionReason - Raison principale de l'impact sur l'état du réseau (OTNetworkReasonNone, OTNetworkReasonUnknown, OTNetworkReasonBandwidthou OTNetworkReasonPacketLoss).

`OTPublisherKitVideoNetworkStats`

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

connectionId - Dans une session relayée, l'identifiant de connexion du client souscrivant au flux. Indéfini dans une session routée.
subscriberId - Dans une session relayée, l'identifiant du client abonné au flux. Indéfini dans une session routée.
videoPacketsLost - Estimation des paquets vidéo perdus.
videoPacketsSent - Paquets vidéo envoyés.
videoBytesSent - Octets vidéo envoyés.
timestamp - Date Unix en millisecondes à laquelle les statistiques ont été recueillies.
startTime - Le timestamp, en millisecondes depuis l'époque Unix, à partir duquel les totaux cumulés ont commencé à s'accumuler.
videoLayers - Tableau de statistiques sur la couche vidéo (voir OTPublisherKitVideoLayerStats).

`OTPublisherKitAudioNetworkStats`

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

connectionId - Dans une session relayée, l'identifiant de connexion du client souscrivant au flux. Indéfini dans une session routée.
subscriberId - Dans une session relayée, l'identifiant du client abonné au flux. Indéfini dans une session routée.
audioPacketsLost - Estimation des paquets perdus.
audioPacketsSent - Paquets audio envoyés.
audioBytesSent - Octets audio envoyés.
timestamp - Horodatage Unix en millisecondes.
startTime - Le timestamp, en millisecondes depuis l'époque Unix, à partir duquel les totaux cumulés ont commencé à s'accumuler.
transport - Statistiques de réseau au niveau du transport.

`OTPublisherKitVideoLayerStats`

Représente une couche simulcast ou une couche SVC.

width - Largeur de la trame encodée.
height - Hauteur du cadre codé.
encodedFrameRate - Images codées par seconde.
bitrate - Débit binaire de la couche (bps).
totalBitrate - Débit de la couche incluant le surdébit RTP (bps).
scalabilityMode - Descripteur SVC/scalability (par exemple, "L3T3").
qualityLimitationReason - Raison de la limitation de la qualité (bande passante, CPU, codec, résolution ou changement de couche).
codec - Le codec utilisé par cette couche vidéo.

`OTSenderStats`

Mesures d'estimation du côté de l'expéditeur (reflétées à la fois sur l'audio et la vidéo).

connectionMaxAllocatedBitrate - Débit maximum estimé pour la connexion de l'expéditeur.
connectionEstimatedBandwidth - Estimation de la largeur de bande actuelle (bps).

`OTSubscriberKitVideoNetworkStats`

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

videoPacketsLost - Estimation des paquets vidéo perdus.
videoPacketsReceived - Paquets vidéo reçus.
videoBytesReceived - Octets vidéo reçus.
timestamp - Date Unix en millisecondes à laquelle les statistiques ont été recueillies.
senderStats - Mesures du côté de l'expéditeur (facultatif).
width - Largeur de la trame décodée en pixels.
height - Hauteur de l'image décodée en pixels.
decodedFrameRate - Images décodées par seconde.
bitrate - Débit binaire vidéo (bps).
totalBitrate - Débit binaire incluant l'overhead RTP (bps).
pauseCount - Nombre de pauses (>5s depuis la dernière image). Inclut les désactivations intentionnelles et les cas de retour audio.
totalPausesDuration - Durée totale de la pause (ms).
freezeCount - Compte de gel (événement de gel défini par WebRTC).
totalFreezesDuration - Durée totale de l'arrêt sur image (ms).
codec - Codec du décodeur actuel.

`OTSubscriberKitAudioNetworkStats`

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

audioPacketsLost - Estimation des paquets perdus.
audioPacketsReceived - Paquets reçus.
audioBytesReceived - Octets reçus.
timestamp - Horodatage Unix en millisecondes.
senderStats - Mesures du côté de l'expéditeur (facultatif).

`OTPublisherKitMediaLinkStats`

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

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

`OTSubscriberKitMediaLinkStats`

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 OTTransportStats)
remotePublisherTransport - Statistiques de transport pour la connexion ascendante de l'éditeur distant (obtenues via statistiques côté expéditeur, voir OTTransportStats). Ces statistiques peuvent être limitées si les statistiques côté expéditeur ne sont pas activées.
networkDegradationSource - Indique la source de la dégradation du réseau (OTNetworkDegradationSourceLocal, OTNetworkDegradationSourceRemote, OTNetworkDegradationSourceBothOrUnclearou OTNetworkDegradationSourceUnknown)

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 senderStatsTrack à la propriété true pour les OTPublisherKitSettings utilisé pour créer l'éditeur.

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

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

Si senderStatsTrack n'est pas activé, aucun canal de statistiques sur les expéditeurs ne sera publié pour cet éditeur. La valeur par défaut est NO.

Abonnement aux statistiques côté expéditeur

Si l'éditeur du flux a activé les statistiques côté émetteur, les abonnés commencent à les recevoir automatiquement dès qu'un auditeur est enregistré pour les statistiques vidéo ou audio, comme décrit ci-dessus.

Mettre en œuvre la méthode de délégation pour les statistiques vidéo :

- (void)subscriber:(OTSubscriberKit *)subscriber
videoNetworkStatsUpdated:(OTSubscriberKitVideoNetworkStats *)stats
{
    // The property may be nil if no sender statistics have been received yet.
    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);
    } else {
        NSLog(@"Sender-side stats not available yet.");
    }
}

De même, mettre en œuvre -subscriber:audioNetworkStatsUpdated: pour les statistiques audio, qui comprend également un senderStats propriété.

Statistiques de réception Événements

Les statistiques du côté de l'expéditeur sont fournies par l'intermédiaire de l'application OTSubscriberKitNetworkStatsDelegate pour la vidéo et l'audio, comme indiqué ci-dessus. Les OTSenderStats, inclus dans le senderStats dans les deux OTSubscriberKitVideoNetworkStats et OTSubscriberKitAudioNetworkStatsLe système de gestion de l'information de l'Union européenne (UE), offre deux propriétés :

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

Ces deux mesures sont calculées par paquet audio-vidéo, de sorte que les mêmes valeurs apparaissent dans les statistiques audio et vidéo. Parce qu'elles reflètent le transport plutôt que les pistes individuelles, les mesures sont partagées entre l'audio et la vidéo.

É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 networkCondition 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 rappels dédiés à l'éditeur et à l'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)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);
    }
}

Rapport statistique RTC

Pour obtenir les statistiques de bas niveau de l'éditeur sur les connexions entre pairs, utilisez la commande [OTPublisherKit getRtcStatsReport:] méthode. Cette méthode fournit des rapports de statistiques RTC pour le flux multimédia.

Il s'agit d'une opération asynchrone. Définir le >[OTPublisherKit rtcStatsReportDelegate]> et mettre en œuvre la propriété >[OTPublisherKitRtcStatsReportDelegate publisher:rtcStatsReport:]> avant d'appeler la méthode [OTPublisherKit getRtcStatsReport:].

Lorsque les statistiques sont disponibles, la mise en œuvre de la fonction >[OTPublisherKitRtcStatsReportDelegate publisher:rtcStatsReport:]> est envoyé. Le message comprend un tableau de OTPublisherRtcStats qui comprend un jsonArrayOfReports 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 la connexion d'un abonné à un homologue, utilisez la commande [OTSubscriberKit getRtcStatsReport:] méthode. Cette méthode permet d'obtenir un rapport de statistiques RTC pour le flux multimédia.

Il s'agit d'une opération asynchrone. Définir le [OTSubscriberKit rtcStatsReportDelegate]> et mettre en œuvre la propriété >[OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport:]> avant d'appeler la méthode [OTSubscriberKit getRtcStatsReport:].

Lorsque les statistiques sont disponibles, la mise en œuvre de la fonction >[OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport:]> est envoyé. Le message comprend un a jsonArrayOfReports 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.

Échantillon

Les Exemple d'application d'observabilité du client SDK iOS de Vonage Video démontre les fonctionnalités d'observabilité du client dans une application mobile construite avec le Client SDK iOS.

Navigation

Observabilité du client : iOS

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 des événements relatifs aux conditions du réseau sur les éditeurs

Activation des statistiques pour les abonnés

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

Réception des événements relatifs à l'état du réseau sur les abonnés

Statistiques Structures de données

OTTransportStats

OTPublisherKitVideoNetworkStats

OTPublisherKitAudioNetworkStats

OTPublisherKitVideoLayerStats

OTSenderStats

OTSubscriberKitVideoNetworkStats

OTSubscriberKitAudioNetworkStats

OTPublisherKitMediaLinkStats

OTSubscriberKitMediaLinkStats