クライアントの可観測性 — Linux

OpenTok Linux SDK には、ビデオセッションにおけるリアルタイムのネットワークおよびメディア統計情報にアクセスするための関数が用意されています。これらの関数は、パケットロス、受信データ量、帯域幅などの詳細なストリーム品質メトリクスを報告し、あらゆるパブリッシャーまたはサブスクライブされたストリームで利用できます。

OpenTok Video SDK は、高レベルな統計 API を通じて詳細なストリーム品質メトリクスを提供します。この API はほとんどのユースケースで推奨されており、音声、動画、ネットワーク、および送信者側の統計情報を、ピア接続の切り替え時にも安定した、セッションを意識した統一された形式で提供します。 高度なデバッグを行うために、この SDK では、未処理のピア接続データを反映した生の WebRTC 統計レポートへのアクセスも提供しています。

SDKはまた、パブリッシャーとサブスクライバーの両方に対して、接続の健全性をハイレベルで評価するネットワーク・コンディション・メトリクスを公開します。これらのメトリクスには、ネットワーク・コンディション・スコア、そのスコアの理由、およびサブスクライバについては、観察された問題の原因が接続のどちらにあるかを示すデグラデーション・ソースが含まれます。参照 ネットワークの状態と劣化の原因 詳細はこちら。

このガイドには、以下のセクションが含まれています：

オーディオ、ビデオ、およびメディアリンクの統計情報API

OpenTok Linux SDK は、パブリッシャーとサブスクライバーの両方について、音声、動画、およびメディアリンクの統計情報を定期的に送信します。これには、パケット数、ビットレート、フレームレートデータ、一時停止／フリーズのメトリクス、コーデック情報、および帯域幅の推定値やネットワーク状態のスコアといったトランスポートレベルのネットワークメトリクスが含まれます。

統計は以下の方法で配信される：

  • otc_publisher_callbacks - パブリッシャー側の統計

  • otc_subscriber_callbacks - 加入者側の統計

それを受け取るには、パブリッシャーかサブスクライバーで適切なコールバックを有効にしてください。

パブリッシャー向け統計の有効化

の on_audio_stats() および on_video_stats() コールバック関数を使用する。 otc_publisher_callbacks を使うことで、パブリッシャーのストリームの統計情報を監視することができます。 パブリッシャーのオーディオとビデオの統計情報を定期的に報告する コールバックメソッドを登録するには を設定します。 on_audio_stats() そして on_video_stats() コールバック関数 パブリッシャーで使用される `otc_publisher_callbacks` 構造体を初期化する際。

登録 otc_publisher_callbacks 構造体はパブリッシャー作成時に作成されます：

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;

そしてコールバックを実装する：

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

これらのコールバック関数は、パブリッシャーのオーディオおよびビデオの統計情報を報告するために 定期的に呼び出されます。各関数には、以下の引数が渡されます。パブリッシャー構造体へのポインタ、 パブリッシャーに対して設定した user_data へのポインタ、 統計情報の配列、およびその配列に含まれる統計情報の数です。stats パラメータは、 によって定義されています。 OTC_PUBLISHER_AUDIO_STATS そして OTC_PUBLISHER_VIDEO_STATS 構造体。ルーティングされたセッション（ を使用するセッション）内のパブリッシャについては、 OpenTok メディアルーター, この配列には1つのオブジェクトが含まれており、 Vonage Video Media Routerに送信される単一のオーディオまたはビデオメディアストリームの統計情報を定義しています。 中継セッションでは、この配列には、公開されたストリームの 各加入者に対応するオブジェクトが含まれます。

パブリッシャーでビデオ画質のイベントを受信する

パブリッシャービデオクオリティのイベント用：

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

パブリッシャーでのネットワーク状態変更イベントの受信

パブリッシャーのネットワーク条件変更イベントを受信するには on_network_condition_changed コールバック otc_publisher_callbacks 構造体

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

他のコールバックと一緒に登録する：

pub_callbacks.on_network_condition_changed = handle_publisher_network_condition;

このコールバックは、パブリッシャーに対するネットワーク状態の重大な変化が 検出されたときにトリガーされる。このコールバックには、トランスポートメトリックを含む現在のメディアリンク統計が含まれます。

加入者統計の有効化

の on_audio_stats() および on_video_stats() コールバック関数を使用する。 otc_subscriber_callbacks を使用して、加入者のストリームの統計を監視する。

登録 otc_subscriber_callbacks サブスクライバを作成するときに

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

コールバックを実装する：

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

加入者のビデオ品質イベントの受信

パブリッシャービデオクオリティのイベント用：

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

加入者側でのネットワーク状態変化イベントの受信

加入者のネットワーク条件変更イベントを受信するには、以下のように設定します。 on_network_condition_changed コールバック otc_subscriber_callbacks 構造体

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

他のコールバックと一緒に登録する：

sub_callbacks.on_network_condition_changed = handle_subscriber_network_condition;

このコールバックは、サブスクライバーまたはリモートパブリッシャーのネッ トワーク状態の重大な変化が検知されたときにトリガーされる。これには、ローカルおよびリモートのトランスポートメトリクスと劣化ソースを含む、現在のメディアリンク統計が含まれる。

統計データ構造

このセクションでは、C SDK オーディオ/ビデオ統計 API が提供する構造体とフィールドの概要を説明します。すべての Video SDK プラットフォームが同じ統計情報セットを公開していますが、各プラットフォームで個々のフィールドの構造や名前の付け方に若干の違いがある場合があります。これらの違いは、基本的なメトリクスの違いではなく、プラットフォーム固有の SDK 設計規約を反映しています。

利用可能な統計とそれが表すものについてのプラットフォームに依存しない説明については、以下を参照のこと。 顧客の観測可能性の概要.

otc_transport_stats

共有トランスポート・レベルのメトリクスを表します。

  • connection_estimated_bandwidth - 推定利用可能接続帯域幅（bps）
  • network_condition - 現在のネットワーク・コンディション・スコアOTC_NETWORK_CONDITION_UNKNOWN, OTC_NETWORK_CONDITION_CRITICAL, OTC_NETWORK_CONDITION_WARNING, OTC_NETWORK_CONDITION_FAIR, OTC_NETWORK_CONDITION_GOODあるいは OTC_NETWORK_CONDITION_EXCELLENT)
  • network_condition_reason - ネットワーク状況に影響を与える主な理由OTC_NETWORK_REASON_NONE, OTC_NETWORK_REASON_UNKNOWN, OTC_NETWORK_REASON_BANDWIDTHあるいは OTC_NETWORK_REASON_PACKET_LOSS)

otc_publisher_video_stats

パブリッシャーのビデオトラックに関する統計を提供します：

  • connection_id - リレーセッションにおいて、ストリームを購読しているクライアントのコネクションID。
  • subscriber_id - リレーセッションにおいて、ストリームにサブスクライブしているクライアントのサブスクライバーIDは、以下のようになる。
  • packets_lost - 失われたビデオパケットの推定値
  • packets_sent - ビデオパケット送信
  • bytes_sent - ビデオ・バイトの送信
  • timestamp - ミリ秒単位のUnixタイムスタンプ
  • start_time - Unixエポックからのミリ秒単位のタイムスタンプ。
  • video_layers - ビデオレイヤーの統計情報の配列 (otc_publisher_video_layer_stats を参照ください)。
  • transport - この出版社の輸送統計

otc_publisher_audio_stats

パブリッシャーのオーディオトラックに関する統計を提供します：

  • connection_id - リレーセッションにおいて、ストリームを購読しているクライアントのコネクションID。
  • subscriber_id - リレーされたセッションでは、加入者ID
  • packets_lost - 失われたオーディオパケットの推定値
  • packets_sent - オーディオパケット送信
  • bytes_sent - オーディオ・バイトの送信
  • timestamp - ミリ秒単位のUnixタイムスタンプ
  • start_time - Unixエポックからのミリ秒単位のタイムスタンプ。
  • transport - この出版社の輸送統計

otc_publisher_video_layer_stats

1つのサイマルキャストまたはSVCレイヤーを表す：

  • width - 符号化フレーム幅
  • height - エンコードされたフレームの高さ
  • encoded_frame_rate - エンコードfps
  • bitrate - レイヤービットレート（bps）
  • total_bitrate - RTPオーバーヘッドを含むレイヤービットレート（bps）
  • scalability_mode - SVC/スケーラビリティ記述子（例：「L3T3）
  • quality_limitation_reason - 品質制限の理由（帯域幅、CPU、コーデック、解像度、レイヤーの変更）
  • codec - このビデオレイヤーに使用されているコーデック

otc_subscriber_video_stats

加入者のビデオトラックに関する統計を提供する：

  • packets_lost - 失われたビデオパケットの推定値
  • packets_received - ビデオパケット受信
  • bytes_received - ビデオ・バイト受信
  • timestamp - ミリ秒単位のUnixタイムスタンプ
  • sender_connection_max_allocated_bitrate - オプションの送信側最大ビットレート
  • sender_connection_estimated_bandwidth - オプションの送信側推定帯域幅
  • width - デコードされたフレーム幅（ピクセル
  • height - デコードされたフレームの高さ（ピクセル
  • decoded_frame_rate - デコード・フレーム/秒
  • bitrate - ビデオビットレート（bps）
  • total_bitrate - RTPオーバーヘッドを含むビットレート（bps）
  • pause_count - ポーズ数（最後のフレームから5秒以上）
  • total_pauses_duration - 全休止時間 (ms)
  • freeze_count - フリーズ回数
  • total_freezes_duration - 合計フリーズ時間（ms）
  • codec - 現在のデコーダー・コーデック

otc_publisher_media_link_stats

パブリッシャー接続のトランスポートレベルの統計情報を提供します。

  • transport - この出版社の輸送統計 otc_transport_stats)

otc_subscriber_media_link_stats

加入者の接続のトランスポートレベルの統計情報を提供する。

  • transport - この加入者のダウンリンク接続のトランスポート統計（以下を参照。 otc_transport_stats)
  • remote_publisher_transport - リモートパブリッシャーのアップリンク接続のトランスポート統計( otc_transport_stats).送信側統計が有効でない場合、制限されることがある。
  • network_degradation_source - ネットワーク劣化の原因があればそれを示す (OTC_NETWORK_DEGRADATION_SOURCE_NONE, OTC_NETWORK_DEGRADATION_SOURCE_LOCAL, OTC_NETWORK_DEGRADATION_SOURCE_REMOTEあるいは OTC_NETWORK_DEGRADATION_SOURCE_BOTH_OR_UNCLEAR)

送信側統計

参照 送信側統計の概要.

送信側統計の有効化

送信者側の統計情報は、購読者が受け取る。送信者側の統計情報を受け取るには、ストリームのパブリッシャーに対して以下をコールして有効にします。 otc_publisher_settings_set_sender_stats_track() 関数を実行してからパブリッシャーを構築してください：

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

送信者統計トラックが有効でない場合、送信者統計チャンネルはこのパブリッシャーには発行されません。デフォルト値は OTC_FALSE.

送信者側の統計情報の受信

パブリッシャーが送信者側の統計情報を有効にしている場合、購読者は stats コールバックを通して自動的に統計情報を受け取ります。 前述.その otc_subscriber_video_stats そして otc_subscriber_audio_stats 構造体には2つの送信側フィールドがある：

  • sender_connection_max_allocated_bitrate - 接続時に推定可能な最大ビットレート
  • sender_connection_estimated_bandwidth - 接続の現在の推定帯域幅

これらのメトリクスは、オーディオとビデオのバンドルごとに計算されるため、ビデオとオーディオの両方の統計に同じ値が表示されます。

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

ネットワークの状態と劣化の原因

SDKは、パブリッシャーとサブスクライバーの両方に対して、コンディションのスコア、そのスコアを駆動する理由、サブスクライバーの劣化ソースを含むリアルタイムのネットワーク・コンディション・メトリクスを提供します。ネットワーク・コンディション・モデル、スコア、理由、およびそれを有効にする方法の詳細については 顧客の観測可能性の概要.

ネットワーク・コンディション・データは2つのチャンネルから入手できる：

  • 定期的な統計： メディアリンク統計イベントには、以下のトランスポートメトリクスが含まれます。 network_condition そして network_condition_reason.購読者向けには、メディアリンクの統計も含まれる。 remote_publisher_transport そして network_degradation_source.参照 パブリッシャーのメディアリンク統計 そして 購読者向けメディアリンクの統計 詳細はこちら。
  • ネットワーク状態の変更イベント： 両方の専用コールバック 出版社 そして 契約者 は、ネットワーク状態の重大な変化が検出されたときにトリガーされる。

以下の例では、加入者ネットワークの状態データを使用して、劣化の原因を特定する方法を示しています：

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統計レポート

パブリッシャーの低レベルのピア接続統計を取得するには otc_publisher_get_rtc_stats_report() 関数。これにより、 メディアストリームのRTC統計レポートが提供されます。 これは非同期操作です。 otc_publisher_rtc_stats_report_cb struct を定義し、それを otc_publisher_set_rtc_stats_report_cb otc_publisher_get_rtc_stats_report() を呼び出す前にこの関数を定義しておく必要があります。統計情報が利用可能になると、 otc_publisher_rtc_stats_report_cb.on_rtc_stats_report() コールバック関数が呼び出されます。 この関数には stats パラメータが含まれており、これは otc_publisher_rtc_stats 構造体。この構造体には、 json_array_of_reports プロパティが含まれています。これは RTC 統計レポートの JSON 配列であり、 Web ブラウザで実装されている RtcStatsReport オブジェクトの形式と類似しています（参照： Mozillaのドキュメント. こちらも参照 このW3Cドキュメント.

サブスクライバの低レベルのピア接続統計を取得するには otc_subscriber_get_rtc_stats_report() 関数。これにより、 メディアストリームのRTC統計レポートが提供されます。これは非同期操作です。 otc_subscriber_rtc_stats_report_cb struct を定義し、それを otc_subscriber_set_rtc_stats_report_cb otc_subscriber_get_rtc_stats_report() を呼び出す前に、この関数を実行してください。統計情報が利用可能になると、 otc_subscriber_rtc_stats_report_cb.on_rtc_stats_report コールバック関数が呼び出されます。このコールバック関数には、 json_array_of_reports パラメータが含まれます。これは RTC 統計レポートの JSON 配列であり、 Web ブラウザで実装されている RtcStatsReport オブジェクトの形式と類似しています（ Mozillaのドキュメント. こちらも参照 このW3Cドキュメント.