Client-Observability – Windows

• Übersicht
• Web
• iOS
• iOS (Swift)
• Android
• Windows
• Linux
• React Native

Das OpenTok Windows SDK bietet Funktionen für den Zugriff auf Echtzeit-Netzwerk- und Medienstatistiken in einer Videositzung. Diese Funktionen liefern detaillierte Kennzahlen zur Streamqualität – wie beispielsweise Paketverlust, empfangene Daten und Bandbreite – und können für jeden Publisher- oder abonnierten Stream verwendet werden.

Das OpenTok Video SDK stellt detaillierte Metriken zur Stream-Qualität über eine hochrangige Statistik-API bereit – empfohlen für die meisten Anwendungsfälle –, die Audio-, Video-, Netzwerk- und senderseitige Statistiken in einer einheitlichen, sitzungsbezogenen Form liefert, die auch bei Wechseln der Peer-Verbindungen stabil bleibt. Für die erweiterte Fehlerbehebung bietet das SDK zudem Zugriff auf den Rohdatenbericht der WebRTC-Statistiken, der unverarbeitete Daten zu Peer-Verbindungen enthält.

Das SDK stellt auch Netzwerkzustandsmetriken zur Verfügung, die eine umfassende Bewertung des Verbindungszustands sowohl für Herausgeber als auch für Abonnenten ermöglichen. Diese Metriken umfassen eine Bewertung des Netzwerkzustands, den Grund für diese Bewertung und - für Abonnenten - eine Verschlechterungsquelle, die angibt, welche Seite der Verbindung für die beobachteten Probleme verantwortlich ist. Siehe Netzzustand und Ursache der Verschlechterung für Einzelheiten.

Dieser Leitfaden umfasst die folgenden Abschnitte:

• API für Audio-, Video- und Medien-Link-Statistiken
• Strukturen der Statistik
• Statistik auf der Absenderseite
• Netzzustand und Ursache der Verschlechterung
• RTC-Statistikbericht

API für Audio-, Video- und Medien-Link-Statistiken

Das OpenTok Windows SDK übermittelt regelmäßig Audio-, Video- und Medienlink-Statistiken sowohl für Publisher als auch für Subscriber. Dazu gehören Paketanzahlen, Bitraten, Bildfrequenzdaten, Metriken zu Pausen und Standbildern, Codec-Informationen sowie Netzwerkmetriken auf Transportebene wie Bandbreitenschätzungen und Bewertungen des Netzwerkzustands.

Statistiken werden über die folgenden Ereignisse geliefert:

• Publisher.AudioStatsUpdated - verlagsseitige Audio-Statistiken
• Publisher.VideoStatsUpdated - Video-Statistiken auf Verlagsseite
• Publisher.MediaLinkStatsUpdated - verlagsseitige Medienverbindungsstatistiken (Transportmetriken)
• Publisher.VideoQualityChanged - Benachrichtigung des Herausgebers über Änderungen der Videoqualität
• Publisher.NetworkConditionChanged - Benachrichtigung über Änderungen der Netzbedingungen durch den Verlag
• Subscriber.AudioStatsUpdated - Audio-Statistiken auf der Abonnentenseite
• Subscriber.VideoStatsUpdated - Video-Statistiken auf der Abonnentenseite
• Subscriber.MediaLinkStatsUpdated - teilnehmerseitige Medienverbindungsstatistiken (Transportmetriken)
• Subscriber.VideoQualityChanged - Benachrichtigung der Abonnenten über Änderungen der Videoqualität
• Subscriber.NetworkConditionChanged - Benachrichtigung über Änderungen der Teilnehmernetzbedingungen

Um sie zu empfangen, setzen Sie den entsprechenden Event-Handler auf dem Publisher oder Subscriber.

Freigabe von Statistiken für Verleger

Setzen Sie die entsprechenden Ereignisbehandler für Publisher.AudioStatsUpdated und 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}");
    }
};

Diese Ereignisse werden in regelmäßigen Abständen gesendet, um Audio- und Videostatistiken für den Herausgeber zu melden. Die Ereignisbehandler für diese Ereignisse werden in einem Array von AudioNetworkStats und VideoNetzwerkStatistiken Jeder Methode werden zwei Objekte übergeben: der Herausgeber und ein Array von stats Objekten. Für einen Verleger in einer gerouteten Sitzung (einer, die die OpenTok Media Router, enthält das Array ein Objekt, das die Statistiken für den einzelnen Audio- oder Videomedienstream definiert, der an den Vonage Video Media Router gesendet wird. In einer weitergeleiteten Sitzung enthält das Array ein Objekt für jeden Teilnehmer des veröffentlichten Streams.

Empfang von Ereignissen in Videoqualität bei den Herausgebern

Wenn Sie auch an Videoqualitätsereignissen interessiert sind, implementieren Sie diesen Handler:

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

Empfang von Ereignissen zu Änderungen des Netzwerkzustands auf den Publishern

Um Ereignisse zur Änderung von Netzwerkbedingungen für den Herausgeber zu erhalten, abonnieren Sie die Publisher.NetworkConditionChanged Veranstaltung:

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

Dieses Ereignis wird ausgelöst, wenn beim Publisher eine wesentliche Änderung der Netzwerkbedingungen festgestellt wird. Es enthält die aktuellen Statistiken zur Medienverbindung sowie Transportkennzahlen.

Aktivieren von Statistiken für Abonnenten

Setzen Sie die entsprechenden Ereignisbehandler für Subscriber.AudioStatsUpdated und 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}");
};

Empfang von Videoqualitätsereignissen bei den Abonnenten

Wenn Sie auch an Videoqualitätsereignissen interessiert sind, implementieren Sie diesen Handler:

subscriber.VideoQualityChanged += (sender, args) =>
{
    Console.WriteLine($"Subscriber video quality event: {args.Reason}");
};

Empfang von Ereignissen zu Änderungen des Netzzustands auf dem Teilnehmergerät

Um Ereignisse zur Änderung der Netzbedingungen für den Teilnehmer zu erhalten, abonnieren Sie die Subscriber.NetworkConditionChanged Veranstaltung:

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

Dieses Ereignis wird ausgelöst, wenn eine wesentliche Änderung der Netzwerkbedingungen beim Teilnehmer oder beim Remote-Publisher festgestellt wird. Es enthält die aktuellen Statistiken zur Medienverbindung mit lokalen und Remote-Transportmetriken sowie die Ursache für die Beeinträchtigung.

Statistik-Datenstrukturen

In diesem Abschnitt werden die Strukturen und Felder beschrieben, die von der Windows Video SDK-Audio- und Videostatistik-API bereitgestellt werden. Während alle Video SDK-Plattformen denselben Satz an Statistiken bereitstellen, kann es geringfügige Unterschiede in der Strukturierung oder Benennung einzelner Felder auf den einzelnen Plattformen geben. Diese Unterschiede spiegeln eher plattformspezifische SDK-Designkonventionen als Unterschiede in den zugrunde liegenden Metriken wider.

Eine plattformunabhängige Erläuterung der verfügbaren Statistiken und ihrer Bedeutung finden Sie unter Übersicht über die Beobachtbarkeit der Kunden.

TransportStats

Stellt Metriken auf Transportebene dar.

• ConnectionEstimatedBandwidth - Geschätzte verfügbare Verbindungsbandbreite (bps)
• Condition - Aktuelle Netzzustandsbewertung (NetworkCondition.Unknown, NetworkCondition.Critical, NetworkCondition.Warning, NetworkCondition.Fair, NetworkCondition.Good, oder NetworkCondition.Excellent)
• NetworkConditionReason - Hauptgrund für die Beeinträchtigung des Netzzustandes (NetworkReason.None, NetworkReason.Unknown, NetworkReason.Bandwidth, oder NetworkReason.PacketLoss)

Publisher.AudioNetworkStats

Liefert Statistiken über die Audiospur eines Verlags.

• ConnectionId - Teilnehmerverbindungs-ID (nur weitergeleitet)
• SubscriberId - Teilnehmer-ID (nur weitergeleitet)
• PacketsLost - Insgesamt verlorene Audiopakete
• PacketsSent - Insgesamt gesendete Audiopakete
• BytesSent - Insgesamt gesendete Audio-Bytes
• Timestamp - Zeitstempel der Erfassung der Statistiken (ms)
• StartTime - Zeitstempel des Beginns der kumulativen Summen (ms)

Publisher.VideoNetworkStats

Liefert Statistiken über die Videospur eines Herausgebers.

• ConnectionId - Teilnehmerverbindungs-ID (nur weitergeleitet)
• SubscriberId - Teilnehmer-ID (nur weitergeleitet)
• PacketsLost - Video-Pakete verloren
• PacketsSent - Gesendete Videopakete
• BytesSent - Gesendete Video-Bytes
• Timestamp - Zeitstempel der Erfassung der Statistiken
• StartTime - Zeitstempel des Beginns der kumulierten Summen
• VideoLayers - Liste der Simulcast/SVC-Ebenen (VideoLayerStats)

Publisher.VideoLayerStats

Stellt eine einzelne Simulcast- oder SVC-Videoebene dar.

• Width - Kodierte Bildbreite
• Height - Kodierte Rahmenhöhe
• EncodedFrameRate - Kodierte Bilder pro Sekunde
• Bitrate - Bitrate der Schicht (bps)
• TotalBitrate - Bitrate einschließlich RTP-Overhead (bps)
• ScalabilityMode - SVC/Skalierbarkeitsbeschreibung (z. B. "L3T3")
• QualityLimitationReason - Grund für die Qualitätsminderung
• Codec - Für diese Ebene verwendeter Codec

Publisher.PublisherMediaLinkStats

Liefert Statistiken auf Transportebene für die Verbindung eines Verlags.

• Transport - Verkehrsstatistiken für diesen Verlag (siehe TransportStats)

Subscriber.AudioNetworkStatsEventArgs

Liefert Statistiken über die Audiospur eines Abonnenten.

• PacketsLost - Geschätzte verlorene Audiopakete
• PacketsReceived - Empfangene Audiopakete
• BytesReceived - Empfangene Audio-Bytes
• Timestamp - Zeitstempel der Erfassung der Statistiken
• SenderStats - Absenderseitige Netzbewertung (optional)

Subscriber.VideoNetworkStatsEventArgs

Liefert Statistiken über die Videospur eines Abonnenten.

• PacketsLost - Video-Pakete verloren
• PacketsReceived - Empfangene Videopakete
• BytesReceived - Empfangene Video-Bytes
• Timestamp - Zeitstempel der Erfassung der Statistiken
• SenderStats - Absenderseitige Netzbewertung (optional)
• Width - Dekodierte Bildbreite
• Height - Dekodierte Rahmenhöhe
• DecodedFrameRate - Dekodierte Bilder pro Sekunde
• Bitrate - Video-Bitrate (bps)
• TotalBitrate - Gesamtbitrate einschließlich RTP-Overhead
• PauseCount - Numbers of video pauses (>5s ohne Frame)
• TotalPausesDuration - Gesamtpausendauer (ms)
• FreezeCount - Numbers von WebRTC-definierten Einfrierungen
• TotalFreezesDuration - Gesamtdauer des Einfrierens (ms)
• Codec - Decoder Codec

Subscriber.SubscriberMediaLinkStats

Liefert Statistiken auf Transportebene für die Verbindungen eines Teilnehmers, einschließlich Einblick in die Netzwerkleistung des entfernten Herausgebers. So können Applications diagnostizieren, ob Verbindungsprobleme vom Downlink des Teilnehmers oder vom Uplink des Publishers ausgehen.

• Transport - Transportstatistiken für die Downlink-Verbindung dieses Teilnehmers (siehe TransportStats)
• RemotePublisherTransport - Transportstatistiken für die Uplink-Verbindung des Remote Publishers (siehe TransportStats). Kann eingeschränkt sein, wenn die absenderseitigen Statistiken nicht aktiviert sind.
• NetworkDegradationSource - Gibt die Quelle der Netzbeeinträchtigung an, falls vorhanden (NetworkDegradationSource.None, NetworkDegradationSource.Local, NetworkDegradationSource.Remote, oder NetworkDegradationSource.BothOrUnclear)

Statistik auf der Absenderseite

Siehe die Übersicht der Absenderstatistiken.

Aktivieren von Statistiken auf der Absenderseite

Senderstatistiken werden von den Abonnenten empfangen. Um absenderseitige Statistiken zu erhalten, aktivieren Sie sie für den Herausgeber des Streams, indem Sie die Option HasSenderStatsTrack Eigenschaft zu true bei der Erstellung des Verlags:

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

Publisher publisher = publisherBuilder.Build();

Wenn HasSenderStatsTrack nicht aktiviert ist, wird kein Absenderstatistikkanal für diesen Verlag veröffentlicht. Der Standardwert ist false.

Empfang von Statistiken auf der Absenderseite

Wenn der Herausgeber die Absenderstatistik aktiviert hat, erhalten die Abonnenten diese automatisch über die VideoStatsUpdated und AudioStatsUpdated Veranstaltungen oben beschrieben. Die SenderStats Eigenschaft auf beiden VideoNetworkStatsEventArgs und AudioNetworkStatsEventArgs liefert zwei Metriken:

• ConnectionMaxAllocatedBitrate - Die maximale Bitrate, die für die Verbindung geschätzt werden kann
• ConnectionEstimatedBandwidth - Die aktuell geschätzte Bandbreite für die Verbindung

Diese Metriken werden pro Audio-Video-Bündel berechnet, so dass in den Video- und Audiostatistiken dieselben Werte erscheinen.

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

Netzzustand und Ursache der Verschlechterung

Das SDK liefert sowohl für Publisher als auch für Abonnenten Echtzeit-Netzwerkzustandsmetriken, einschließlich einer Zustandsbewertung, des Grundes für diese Bewertung und einer Verschlechterungsquelle für Abonnenten. Eine vollständige Erläuterung des Netzwerkzustandsmodells, der Bewertungen, der Gründe und der Aktivierung finden Sie in der Übersicht über die Beobachtbarkeit der Kunden.

Netzzustandsdaten sind über zwei Kanäle verfügbar:

• Regelmäßige Statistiken: Die Medienverbindungsstatistiken enthalten Transportmetriken mit Condition und NetworkConditionReason. Für Abonnenten umfasst die Medienlink-Statistik auch RemotePublisherTransport und NetworkDegradationSource.
• Ereignisse, bei denen sich der Netzzustand ändert: Spezielle Ereignisse werden sowohl auf dem Publisher als auch auf dem Subscriber ausgelöst, wenn eine wesentliche Änderung der Netzwerkbedingungen festgestellt wird.

Das folgende Beispiel zeigt, wie die Daten über den Zustand des Teilnehmernetzes verwendet werden können, um die Ursache der Verschlechterung zu ermitteln:

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

RTC-Statistikbericht

Verwenden Sie die RTC-Statistik-API, um Diagnosedaten auf WebRTC-Ebene abzurufen. Um Low-Level-Statistiken zur Peer-Verbindung eines Publishers abzurufen, verwenden Sie die Publisher.GetRtcStatsReport() Methode. Diese liefert RTC-Statistikberichte für den Medienstrom. Hierbei handelt es sich um einen asynchronen Vorgang. Sobald die Statistiken verfügbar sind, wird das Ereignis „RtcStatsReport“ gesendet. Das Objekt „RtcStatsReportArgs“ enthält ein Array von Herausgeber RtcStats Objekte, die eine Eigenschaft namens „JsonArrayOfReports“ enthalten. Dabei handelt es sich um ein JSON-Array mit RTC-Statistikberichten, deren Format dem des in Webbrowsern implementierten RtcStatsReport-Objekts ähnelt (siehe diese Mozilla-Dokumente. Siehe auch diese W3C-Dokumentation.

Um detaillierte Statistiken zur Peer-Verbindung eines Teilnehmers abzurufen, verwenden Sie den Befehl Subscriber.GetRtcStatsReport() Methode. Diese liefert einen RTC-Statistikbericht für den Medienstrom. Hierbei handelt es sich um einen asynchronen Vorgang. Sobald die Statistiken verfügbar sind, wird das Ereignis „RtcStatsReport“ gesendet. RtcStatsReportArgs Das Objekt enthält eine Eigenschaft namens „JsonArrayOfReports“. Dabei handelt es sich um ein JSON-Array mit RTC-Statistikberichten, deren Format dem des in Webbrowsern implementierten RtcStatsReport-Objekts ähnelt (siehe diese Mozilla-Dokumente. Siehe auch diese W3C-Dokumentation.

Anfordern eines RTC-Statistikberichts für einen Verlag:

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

publisher.GetRtcStatsReport();