Client-Beobachtbarkeit: Linux

Das Vonage Video SDK stellt detaillierte Metriken zur Stream-Qualität über eine High-Level-Statistik-API zur Verfügung, die für die meisten Anwendungsfälle empfohlen wird und die Audio-, Video-, Netzwerk- und Absenderstatistiken in einer einheitlichen, sitzungsspezifischen Form bereitstellt, die über Peer-Verbindungsübergänge hinweg stabil bleibt. Für fortgeschrittenes Debugging bietet das SDK auch Zugriff auf den rohen WebRTC-Statistikbericht, der unverarbeitete Peer-Verbindungsdaten wiedergibt.

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.

Audio-, Video- und Medienlink-Statistik-API

Das Vonage Video Linux SDK sendet in regelmäßigen Abständen Audio-, Video- und Media-Link-Netzwerkstatistiken sowohl für Publisher als auch für Subscriber. Dazu gehören die Anzahl der Pakete, Bitraten, Frame-Rate-Daten, Pausen-/Freeze-Metriken, Codec-Informationen und Netzwerkmetriken auf Transportebene, wie z. B. Bandbreitenschätzung und Bewertung 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.

Aktivieren 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 wenn Sie die Initialisierung der otc_publisher_callbacks Struktur, die vom Herausgeber zu verwenden.

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 Herausgeber zu melden. Jede Funktion wird wie folgt übergeben: Ein Zeiger auf den Herausgeber Struktur, ein Zeiger auf die user_data die Sie für den Verlag festgelegt haben, ein Array von Statistiken und die Anzahl der Statistiken im Array. Der Parameter stats ist definiert durch den otc_verlag_audio_statistiken und otc_verlag_video_statistiken strukturen. Für einen Verleger in einer gerouteten Sitzung (eine, die die OpenTok Medien-Router), enthält das Array ein Objekt, das die Statistiken für den einzelnen Audio- oder Video-Medienstrom, der an den Vonage Video Media Router gesendet wird. Bei einer weitergeleiteten Sitzung enthält das Array ein Objekt für jeden Teilnehmer des des veröffentlichten Streams.

Empfang von Videoqualitätsereignissen 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);
}

Empfang von Netzwerkzustandsereignissen 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,
                                          size_t number_of_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 Netzwerkzustandsereignissen auf dem Teilnehmer

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)

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

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_subscriber_audio_stats

Liefert Statistiken über die Audiospur eines Abonnenten:

  • packets_lost - Geschätzte verlorene Pakete
  • packets_received - Empfangene Pakete
  • bytes_received - Empfangene Bytes
  • audio_level - Audiopegel (0-1,0)
  • 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
  • transport - Lokale Transport- und Netzwerkstatistiken für diesen Teilnehmer (siehe otc_transport_stats). Kann eingeschränkt sein, wenn absenderseitige Statistiken und/oder Audio-Fallback deaktiviert sind.
  • remote_publisher_transport - Transport- und Netzwerkstatistiken für Remote Publisher (siehe otc_transport_stats). Kann eingeschränkt sein, wenn absenderseitige Statistiken und/oder Audio-Fallback deaktiviert sind.

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 der absenderseitigen Statistik

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.

Empfangen von absenderseitigen Statistiken

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 Verschlechterung Quelle

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 transport Feld der Publisher- und Subscriber-Stats-Strukturen enthält network_condition und network_condition_reason. Die Abonnentenstatistiken geben auch Aufschluss über remote_publisher_transport und network_degradation_source. Siehe Strukturen der Statistik 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_video_stats* video_stats,
                                          const struct otc_subscriber_audio_stats* audio_stats,
                                          enum otc_network_reason reason) {
    enum otc_network_condition local_condition = video_stats->transport.network_condition;
    enum otc_network_condition remote_condition = video_stats->remote_publisher_transport.network_condition;
    enum otc_network_degradation_source source = video_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. Sie liefert RTC-Statistikberichte für den Medienstrom. Dies ist ein asynchroner Vorgang. Erstellen einer otc_publisher_rtc_stats_report_cb struct und leiten es in die otc_publisher_set_rtc_stats_report_cb Funktion vor dem Aufruf von otc_publisher_get_rtc_stats_report(). Wenn die Statistiken verfügbar sind, wird die otc_publisher_rtc_stats_report_cb.on_rtc_stats_report() Callback-Funktion aufgerufen wird. Diese Funktion enthält eine stats Parameter, der ein Zeiger auf ein Array von otc_publisher_rtc_stats Strukturen. Diese Struktur enthält eine json_array_of_reports Eigenschaft. Dies ist ein JSON-Array mit RTC-Statistikberichten, die dem Format des in Webbrowsern implementierten RtcStatsReport-Objekts ähnlich sind (siehe diese Mozilla-Dokumente).

Um Low-Level-Peer-Verbindungsstatistiken für einen Teilnehmer zu erhalten, verwenden Sie den Befehl otc_subscriber_get_rtc_stats_report() Funktion. Diese Funktion liefert einen RTC-Statistikbericht für den Medienstrom.

Dies ist ein asynchroner Vorgang. Erstellen einer otc_subscriber_rtc_stats_report_cb Struktur und übergeben Sie sie an die otc_subscriber_set_rtc_stats_report_cb Funktion vor dem Aufruf von otc_subscriber_get_rtc_stats_report(). Wenn die Statistiken verfügbar sind, wird die otc_subscriber_rtc_stats_report_cb.on_rtc_stats_report Callback-Funktion aufgerufen wird.

Diese Rückruffunktion enthält eine json_array_of_reports Parameter. Dies ist ein JSON-Array mit RTC-Statistikberichten, die dem Format des in Webbrowsern implementierten RtcStatsReport-Objekts ähnlich sind (siehe diese Mozilla-Dokumente).

Siehe auch diese W3C-Dokumentation.