統計エクスポーター機能¶
注意
ユーザーエージェント統計 API は 2025 年 6 月リリースの Sora にて廃止します 代わりに 統計ウェブフック機能 をご利用ください。
注意
この機能を利用する場合は事前にサポートまでご連絡ください
警告
この機能は 実験的機能 のため、正式版では仕様が変更される可能性があります
概要¶
Sora 経由で統計情報コレクターに向けて統計情報をエクスポートする機能です。
注意¶
IPv6 非対応¶
現時点で、統計エクスポーターは IPv6 を利用できません。
HTTP/2¶
統計コレクターサーバーは HTTP/2 に対応している必要があります
h2c と h2 の両方に対応しています
http://から始めると h2c を利用しますhttps://から始めると h2 を利用します
WebRTC Stats Collector Kohaku¶
Kohaku は統計エクスポーター対応の統計コレクターです。
設定¶
stats_collector_url¶
統計情報を収集するコレクターの URL を指定します。 HTTP または HTTPS の URL が指定できます。
stats_collector_url = http://192.0.2.10:5890/collector
default_stats_exporter¶
stats_collector_url が指定されていた場合、デフォルトでは統計情報をコレクターに送信します。
もし、統計情報の送信を接続毎に行いたい場合、この設定を false にし、
統計情報を送信したい接続の認証成功時に "stats_exporter": true を払い出すようにしてください。
default_stats_exporter = false
stats_exporter_number¶
統計情報を出力するエクスポーターの数を指定できます。 基本的にはデフォルトの 5 で足りますが、同時接続数が多い場合は変更をお勧めします。
stats_exporter_number = 5
stats_exporter_tls_fullchain_file¶
mTLS を利用するための設定で、中間証明書を含むクライアント証明書を PEM 形式で設定して下さい。
stats_exporter_tls_fullchain_file = /path/to/fullchain.pem
stats_exporter_tls_privkey_file¶
統計コレクターサーバーと mTLS を利用するための設定で、クライアント証明書の秘密鍵を PEM 形式で設定して下さい。
重要
秘密鍵にパスフレーズが設定されている場合はエラーとなります
stats_exporter_tls_privkey_file = /path/to/privkey.pem
stats_exporter_tls_verify_cacert_file¶
注釈
CA 証明書を指定しない場合、OS 組み込みの証明書を利用します。詳細は ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する OS 組み込みのルート CA 証明書について をご確認ください。
統計コレクターサーバーとの通信に HTTPS を利用した際、サーバー証明書のチェックを行う CA ファイルを PEM 形式で設定して下さい。
stats_exporter_tls_verify_cacert_file = /path/to/server_cacert.pem
エクスポーター¶
統計情報をコレクターに対して送ります。
共通¶
type
統計情報の種類情報が入ります
node_name
Sora のノード名が入ります
クラスター機能を利用していない場合は
sora@127.0.0.1です
version
Sora のバージョンが入ります
label
sora.conf に設定された label が入ります
timestamp
Sora が stats を送る直前の時間 RFC3339 形式の (UTC) が入ります
HTTP ヘッダー¶
注釈
JSON のパース時の判断などに利用してください。
注意
x-sora-session-webhook-type は非推奨です、 sora-session-webhook-type を利用してください
統計エクスポーターの HTTP ヘッダー に sora-stats-exporter-type と x-sora-stats-exporter-type というヘッダー名で統計エクスポーターのタイプが入ってきます。
type が connection.user-agent の場合は sora-stats-exporter-type: connection.user-agent と x-sora-stats-exporter-type: connection.user-agent のように値が入ってきます。
type: connection.user-agent¶
クライアントから送られてくるユーザーエージェント統計情報です。
ユーザーエージェント統計情報は W3C の Identifiers for WebRTC's Statistics API に準拠している必要があります。
type
connection.user-agent
channel_id
チャネル ID が入ります
role
session_id
セッション ID が入ります
client_id
connection_id
multistream
simulcast
spotlight
stats
{
"channel_id": "sora",
"session_id": "78K3N8E5M551XEKEWR8QN77PHW",
"client_id": "NCD5EF3ME900ZDJ3SE27Y6AB6R",
"connection_id": "NCD5EF3ME900ZDJ3SE27Y6AB6R",
"id": "N6W0DBF6A957B01BKNJJR1HC04",
"label": "WebRTC SFU Sora",
"multistream": true,
"spotlight": false,
"simulcast": true,
"stats": [
{
"id": "RTCAudioSource_5",
"kind": "audio",
"timestamp": 1629449091306.655,
"type": "media-source",
"audioLevel": 0.02237006744590594,
"totalAudioEnergy": 0.15581033797981153,
"totalSamplesDuration": 5.089999999999936,
"trackIdentifier": "922dd031-8a4f-4122-9687-ce094fa11ee2"
}, ...
],
"timestamp": "2021-08-20T08:44:51.308778Z",
"type": "connection.user-agent",
"node_name": "sora@127.0.0.1",
"version": "2023.2.0"
}
type: connection.sora¶
現時点ではまだ対応していません
Sora にため込んでいる統計情報です。
type の頻度指定¶
変化が無かったり変化の少ない stats を送る頻度を減らしています。 デフォルト 600 秒間隔にしています。
type: connection.user-agent¶
送信頻度を抑えている Stats Type。
codec
Sora の場合、初期値から変更される項目が無いため
local-candidate
Sora の場合、初期値から変更される項目が無いため
remote-candidate
Sora の場合、初期値から変更される項目が無いため
certificate
Sora の場合、初期値から変更される項目が無いため
peer-connection
Sora の場合、初期値から変更される項目が無いため
track
DEPRECATED 項目のため
stream
DEPRECATED 項目のため
シーケンス図¶
DataChannel シグナリング利用時¶
sequenceDiagram
autonumber
participant C as クライアント
participant S as Sora
participant kohaku as Stats Collector Kohaku
participant tsdb as TimescaleDB
note over C,tsdb: WebRTC 確立
C--)S: Stats over DataChannel
S->>+kohaku: Stats over HTTP/2
kohaku->>+tsdb: Insert Stats
tsdb-->>-kohaku: Ack
kohaku-->>-S: 200 OK