Client-Observability – Linux

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

Das OpenTok Linux SDK bietet Funktionen für den Zugriff auf Echtzeit-Netzwerk- und Medienstatistiken in einer Videositzung. Diese Funktionen liefern detaillierte Kennzahlen zur Stream-Qualitä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 Linux SDK übermittelt regelmäßig Audio-, Video- und Medienlink-Statistiken sowohl für Publisher als auch für Subscriber. Dazu gehören Paketanzahlen, Bitraten, Bildratendaten, Metriken zu Pausen und Standbildern, Codec-Informationen sowie Netzwerkmetriken auf Transportebene wie Bandbreitenschätzungen und Bewertungen des Netzwerkzustands.

Die Statistiken werden durch geliefert:

• otc_publisher_callbacks - verlagsseitige Statistiken

• otc_subscriber_callbacks - Statistiken auf der Abonnentenseite

Um sie zu empfangen, aktivieren Sie den entsprechenden Rückruf auf dem Verleger oder Abonnenten.

Freigabe von Statistiken für Verleger

Verwenden Sie die on_audio_stats() und on_video_stats() Callback-Funktionen der otc_publisher_callbacks um Statistiken für den Stream eines Herausgebers zu überwachen. Um Callback-Methoden für periodische Berichte von Audio- und Videostatistiken zu registrieren für einen Publisher zu registrieren, setzen Sie die on_audio_stats() und on_video_stats() Callback-Funktionen beim Initialisieren der Struktur `otc_publisher_callbacks`, die vom Publisher verwendet werden soll.

Einschreiben otc_publisher_callbacks Struktur bei der Erstellung des Verlags:

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;

Und implementieren Sie die Rückrufe:

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

Diese Callback-Funktionen werden in regelmäßigen Abständen aufgerufen, um Audio- und Videostatistiken für den Publisher zu melden. Jeder Funktion werden folgende Parameter übergeben: Ein Zeiger auf die Publisher-Struktur, ein Zeiger auf die von Ihnen für den Publisher festgelegten `user_data`, ein Array mit Statistiken sowie die Anzahl der Statistiken im Array. Der Parameter „stats“ wird durch die otc_verlag_audio_statistiken und otc_verlag_video_statistiken Strukturen. Für einen Publisher in einer gerouteten Sitzung (d. h. 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

Für Ereignisse in Publisher-Videoqualität:

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

Empfangen von Ereignissen zu Änderungen des Netzwerkzustands auf dem Publisher

Um Ereignisse zur Änderung der Netzwerkbedingungen für den Herausgeber zu erhalten, setzen Sie den on_network_condition_changed Rückruf in der otc_publisher_callbacks Struktur:

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

Registrieren Sie ihn zusammen mit den anderen Rückrufen:

pub_callbacks.on_network_condition_changed = handle_publisher_network_condition;

Dieser Callback wird ausgelöst, wenn eine signifikante Änderung der Netzwerkbedingungen für den Herausgeber festgestellt wird. Er enthält die aktuelle Medienverbindungsstatistik mit Transportmetriken.

Aktivieren von Statistiken für Abonnenten

Verwenden Sie die on_audio_stats() und on_video_stats() Callback-Funktionen der otc_subscriber_callbacks um die Statistiken für den Stream eines Abonnenten zu überwachen.

Einschreiben otc_subscriber_callbacks Struktur bei der Erstellung des Abonnenten:

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

Implementieren Sie die Rückrufe:

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

Empfang von Videoqualitätsereignissen bei den Abonnenten

Für Ereignisse in Publisher-Videoqualität:

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

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

Um Ereignisse zur Änderung der Netzwerkbedingungen für den Teilnehmer zu empfangen, setzen Sie den on_network_condition_changed Rückruf in der otc_subscriber_callbacks Struktur:

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

Registrieren Sie ihn zusammen mit den anderen Rückrufen:

sub_callbacks.on_network_condition_changed = handle_subscriber_network_condition;

Dieser Rückruf wird ausgelöst, wenn eine signifikante Änderung der Netzbedingungen für den Teilnehmer oder den entfernten Herausgeber festgestellt wird. Er enthält die aktuelle Medienverbindungsstatistik mit den lokalen und entfernten Transportmetriken und der Degradationsquelle.

Statistik-Datenstrukturen

In diesem Abschnitt werden die Strukturen und Felder beschrieben, die von der C-SDK-Audio- und Videostatistik-API bereitgestellt werden. Während alle Video SDK Plattformen den gleichen Satz an Statistiken zur Verfügung stellen, kann es geringfügige Unterschiede in der Strukturierung oder Benennung einzelner Felder 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.

otc_transport_stats

Stellt gemeinsame Metriken auf Transportebene dar.

• connection_estimated_bandwidth - Geschätzte verfügbare Verbindungsbandbreite (bps)
• network_condition - Aktuelle Netzzustandsbewertung (OTC_NETWORK_CONDITION_UNKNOWN, OTC_NETWORK_CONDITION_CRITICAL, OTC_NETWORK_CONDITION_WARNING, OTC_NETWORK_CONDITION_FAIR, OTC_NETWORK_CONDITION_GOOD, oder OTC_NETWORK_CONDITION_EXCELLENT)
• network_condition_reason - Hauptgrund für die Beeinträchtigung des Netzzustandes (OTC_NETWORK_REASON_NONE, OTC_NETWORK_REASON_UNKNOWN, OTC_NETWORK_REASON_BANDWIDTH, oder OTC_NETWORK_REASON_PACKET_LOSS)

otc_publisher_video_stats

Liefert Statistiken über die Videospur eines Herausgebers:

• connection_id - Bei einer weitergeleiteten Sitzung die Verbindungs-ID des Clients, der den Stream abonniert
• subscriber_id - In einer weitergeleiteten Sitzung wird die Abonnenten-ID des Clients, der den Stream abonniert, angezeigt.
• packets_lost - Geschätzte verlorene Videopakete
• packets_sent - Gesendete Videopakete
• bytes_sent - Gesendete Video-Bytes
• timestamp - Unix-Zeitstempel in Millisekunden
• start_time - Der Zeitstempel in Millisekunden seit der Unix-Epoche, ab dem die kumulativen Summen zu kumulieren begannen
• video_layers - Array mit Statistiken zur Videoebene (siehe otc_publisher_video_layer_stats)
• transport - Transportstatistiken für diesen Verlag

otc_publisher_audio_stats

Liefert Statistiken über die Audiospur eines Verlags:

• connection_id - Bei einer weitergeleiteten Sitzung die Verbindungs-ID des Clients, der den Stream abonniert
• subscriber_id - Bei einer weitergeleiteten Sitzung wird die Teilnehmer-ID
• packets_lost - Geschätzte verlorene Audiopakete
• packets_sent - Gesendete Audiopakete
• bytes_sent - Gesendete Audio-Bytes
• timestamp - Unix-Zeitstempel in Millisekunden
• start_time - Der Zeitstempel in Millisekunden seit der Unix-Epoche, ab dem die kumulativen Summen zu kumulieren begannen
• transport - Transportstatistiken für diesen Verlag

otc_publisher_video_layer_stats

Steht für eine Simulcast- oder SVC-Ebene:

• width - Kodierte Bildbreite
• height - Kodierte Rahmenhöhe
• encoded_frame_rate - Kodierte fps
• bitrate - Bitrate der Schicht (bps)
• total_bitrate - Layer-Bitrate einschließlich RTP-Overhead (bps)
• scalability_mode - SVC/Skalierbarkeitsdeskriptor (z. B. "L3T3")
• quality_limitation_reason - Grund für die Qualitätseinschränkung (Bandbreite, CPU, Codec, Auflösung oder Ebenenwechsel)
• codec - Für diese Videoebene verwendeter Codec

otc_subscriber_video_stats

Liefert Statistiken über die Videospur eines Abonnenten:

• packets_lost - Geschätzte verlorene Videopakete
• packets_received - Empfangene Videopakete
• bytes_received - Empfangene Video-Bytes
• timestamp - Unix-Zeitstempel in Millisekunden
• sender_connection_max_allocated_bitrate - Optionale maximale Bitrate auf der Senderseite
• sender_connection_estimated_bandwidth - Optionale geschätzte Bandbreite auf der Absenderseite
• width - Dekodierte Bildbreite in Pixel
• height - Dekodierte Bildhöhe in Pixel
• decoded_frame_rate - Dekodierte Bilder pro Sekunde
• bitrate - Video-Bitrate (bps)
• total_bitrate - Bitrate einschließlich RTP-Overhead (bps)
• pause_count - Numbers of pauses (>5s since last frame)
• total_pauses_duration - Gesamtpausendauer (ms)
• freeze_count - Numbers von Einfrierungen
• total_freezes_duration - Gesamtdauer des Einfrierens (ms)
• codec - Aktueller Decoder Codec

otc_publisher_media_link_stats

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

• transport - Verkehrsstatistiken für diesen Verlag (siehe otc_transport_stats)

otc_subscriber_media_link_stats

Liefert Statistiken auf Transportebene für die Verbindungen eines Teilnehmers.

• transport - Transportstatistiken für die Downlink-Verbindung dieses Teilnehmers (siehe otc_transport_stats)
• remote_publisher_transport - Transportstatistiken für die Uplink-Verbindung des Remote Publishers (siehe otc_transport_stats). Kann eingeschränkt sein, wenn die absenderseitigen Statistiken nicht aktiviert sind.
• network_degradation_source - Gibt die Quelle der Netzbeeinträchtigung an, falls vorhanden (OTC_NETWORK_DEGRADATION_SOURCE_NONE, OTC_NETWORK_DEGRADATION_SOURCE_LOCAL, OTC_NETWORK_DEGRADATION_SOURCE_REMOTE, oder OTC_NETWORK_DEGRADATION_SOURCE_BOTH_OR_UNCLEAR)

Statistik auf der Absenderseite

Siehe die Übersicht der Absenderstatistiken.

Aktivieren von Statistiken auf der Absenderseite

Absenderstatistiken werden von den Abonnenten empfangen. Um absenderseitige Statistiken zu erhalten, aktivieren Sie sie für den Herausgeber des Streams durch den Aufruf otc_publisher_settings_set_sender_stats_track() Funktion, bevor Sie den Verlag erstellen:

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

Wenn der Absenderstatistik-Track nicht aktiviert ist, wird für diesen Verlag kein Absenderstatistik-Kanal veröffentlicht. Der Standardwert ist OTC_FALSE.

Empfang von Statistiken auf der Absenderseite

Wenn der Herausgeber Statistiken auf der Absenderseite aktiviert hat, erhalten die Abonnenten diese automatisch über die Statistik-Callbacks oben beschrieben. Die otc_subscriber_video_stats und otc_subscriber_audio_stats structs enthalten zwei absenderseitige Felder:

• sender_connection_max_allocated_bitrate - Die maximale Bitrate, die für die Verbindung geschätzt werden kann
• sender_connection_estimated_bandwidth - 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.

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

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 network_condition und network_condition_reason. Für Abonnenten umfasst die Medienlink-Statistik auch remote_publisher_transport und network_degradation_source. Siehe Statistiken zu Medienlinks von Herausgebern und Statistiken zu den Medienlinks der Abonnenten für Einzelheiten.
• Ereignisse, bei denen sich der Netzzustand ändert: Dedizierte Rückrufe auf beiden Herausgeber und Teilnehmer werden ausgelöst, wenn eine signifikante Änderung der Netzbedingungen 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:

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

RTC-Statistikbericht

Um Low-Level-Peer-Verbindungsstatistiken für einen Publisher zu erhalten, verwenden Sie die otc_publisher_get_rtc_stats_report() Funktion. Diese liefert RTC-Statistikberichte für den Medienstrom. Dies ist ein asynchroner Vorgang. Erstellen Sie eine otc_publisher_rtc_stats_report_cb struct und übergebe sie an die otc_publisher_set_rtc_stats_report_cb Funktion vor dem Aufruf von `otc_publisher_get_rtc_stats_report()`. Sobald die Statistiken verfügbar sind, wird die Callback-Funktion `otc_publisher_rtc_stats_report_cb.on_rtc_stats_report()` aufgerufen. Diese Funktion enthält einen Parameter „stats“, bei dem es sich um einen Zeiger auf ein Array von otc_publisher_rtc_stats Strukturen. Diese Struktur enthält eine Eigenschaft namens „json_array_of_reports“. Dabei handelt es sich um ein JSON-Array mit RTC-Statistikberichten, die dem Format des in Webbrowsern implementierten RtcStatsReport-Objekts ähneln (siehe diese Mozilla-Dokumente. Siehe auch diese W3C-Dokumentation.

Um Low-Level-Peer-Verbindungsstatistiken für einen Teilnehmer zu erhalten, verwenden Sie die otc_subscriber_get_rtc_stats_report() Funktion. Diese liefert einen RTC-Statistikbericht für den Medienstrom. Hierbei handelt es sich um einen asynchronen Vorgang. Erstellen Sie eine otc_subscriber_rtc_stats_report_cb struct und übergebe sie an die otc_subscriber_set_rtc_stats_report_cb Funktion vor dem Aufruf von otc_subscriber_get_rtc_stats_report(). Sobald die Statistiken verfügbar sind, otc_subscriber_rtc_stats_report_cb.on_rtc_stats_report Die Callback-Funktion wird aufgerufen. Diese Callback-Funktion enthält einen Parameter „json_array_of_reports“. 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.