統計ウェブフック¶
注意
この機能を利用する場合は事前にサポートまでご連絡ください
警告
この機能は 実験的機能 のため、正式版では仕様が変更される可能性があります
概要¶
統計情報をウェブフックで送信する機能です。
注意¶
sora.conf の stats_webhook_url を有効にしない場合、 log/stats_webhook.jsonl は生成されません。
ログ¶
統計ウェブフックのログは log/stats_webhook.jsonl と log/stats_webhook_error.jsonl に出力されます。
統計ウェブフックのログではデフォルトで出力されません。
stats_webhook_url を有効にしたとしても stats_webhook_log を true に設定するまでは、
ログが出力されません。
stats_webhook.jsonl¶
統計ウェブフックで送信した すべて の処理を書き込みます。
stats_webhook_error.jsonl¶
統計ウェブフックの送信が失敗した処理を書き込みます。
統計ウェブフックの間隔¶
Sora は一定間隔でクライアントへ統計情報を要求します。
統計ウェブフックの送信間隔はクライアントが送ってくる RTC 統計情報の間隔に依存します。デフォルトは 60 秒です。
WebSocket シグナリングを利用している場合¶
websocket_stats_timer_interval に指定した間隔になります。
WebSocket の場合は "type": "ping" に "stats": true を付けて送信することで、
クライアントへ統計情報を要求します。
クライアントは "type": "pong" で "stats": ... に統計情報を含めて送ります。
この "stats" が統計ウェブフックの "stats" 項目として送信されます。
DataChannel シグナリングを利用している場合¶
data_channel_stats_timer_interval に指定した間隔になります。
DataChannel シグナリングの場合は stats ラベルを利用して、
"type": "req-stats" を送ってクライアントへ統計情報を要求します。
クライアントは stats ラベルを利用して、
"type": "stats" で "reports" に統計情報を含めて送ります。
この "reports" が統計ウェブフックの "stats" 項目として送信されます。
設定¶
stats_webhook_url¶
統計情報を送信するウェブフック URL を指定します。 HTTP または HTTPS の URL が指定できます。
stats_webhook_url = http://192.0.2.10:5890/sora/webhook/stats
stats_webhook_log¶
統計情報ウェブフックのログを出力するかどうかを指定します。デフォルトは false で出力しません。
統計情報ウェブフックの送信した 全ての処理 は
log/stats_webhook.jsonlログに出力されます統計情報ウェブフックの送信が 失敗した処理 は
log/stats_webhook_error.jsonlログに出力されます
stats_webhook_log = true
ignore_connection_rtc_webhook¶
統計情報ウェブフックの type: connection.rtc を送信するかどうかを指定します。デフォルトは false で送信します。
rtc_stats_log¶
統計情報ウェブフックの type: connection.rtc の stats をリストではなく個別に rtc_stats.jsonl として出力するどうかを指定します。
ログは log/rtc_stats.jsonl に出力されます。
rtc_stats_log = true
stats_webhook_worker_number¶
統計ウェブフックのワーカー数を指定できます。 基本的にはデフォルトの 5 で足りますが、同時接続数が多い場合は変更をお勧めします。
stats_webhook_worker_number = 5
統計情報¶
統計情報をウェブフック URL に対して送信します
共通¶
type
統計情報の種類が入ります
id
ウェブフック ID が入ります
node_name
Sora のノード名が入ります
クラスター機能を利用していない場合は
sora@127.0.0.1です
version
Sora のバージョンが入ります
label
sora.conf に設定された label が入ります
timestamp
Sora が stats を送る直前の時間 RFC3339 形式 (UTC) が入ります
HTTP ヘッダー¶
注釈
JSON のパース時の判断などに利用してください。
統計ウェブフックの HTTP ヘッダー に sora-stats-webhook-type というヘッダー名で統計ウェブフックのタイプが入ってきます。
type が connection.rtc の場合は sora-stats-webhook-type: connection.rtc が入ってきます。
type: connection.rtc¶
クライアントから送られてくる統計情報です。
クライアント統計情報は W3C の Identifiers for WebRTC's Statistics API に準拠している必要があります。
type
connection.rtc
channel_id
チャネル ID が入ります
role
session_id
セッション ID が入ります
client_id
bundle_id
connection_id
multistream
simulcast
spotlight
stats
{
"channel_id": "sora",
"session_id": "78K3N8E5M551XEKEWR8QN77PHW",
"client_id": "NCD5EF3ME900ZDJ3SE27Y6AB6R",
"bundle_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.rtc",
"node_name": "sora@127.0.0.1",
"version": "2024.1.0",
"log_written": false
}
stats 項目に含まれる統計情報の送信頻度¶
変化が無かったり変化の少ない stats 項目に含まれる統計情報を送る頻度を減らしています。
デフォルト 600 秒間隔にしています。
type: connection.rtc¶
送信頻度を抑えている RTCStatsType は以下の通りです。
codec
Sora の場合、初期値から変更される項目が無いため
local-candidate
Sora の場合、初期値から変更される項目が無いため
remote-candidate
Sora の場合、初期値から変更される項目が無いため
certificate
Sora の場合、初期値から変更される項目が無いため
peer-connection
Sora の場合、初期値から変更される項目が無いため
track
DEPRECATED 項目のため
stream
DEPRECATED 項目のため
これらの統計情報は 600 秒間隔で stats 項目に含まれるようになります。
RTC 統計情報ログ出力¶
sora.conf で rtc_stats_log = true に設定すると、 log/rtc_stats.jsonl に RTC 統計情報が出力されます。
解析をしやすくするため、このログは type: connection.rtc の stats をリストではなく個別に出力します。
項目¶
rtc_timestamp
RTCStats の timestamp が浮動小数点で入ります
rtc_type
RTCStats の type が文字列で入ります
rtc_id
RTCStats の id が文字列で入ります
rtc_data
RTCStats がそのまま入ります
例¶
{
"connection_id": "16ZN7HHK5H3PFDFRZCZQN3WVD4",
"id": "Z47B1V0DBN7R1AV90HY98CF6Y8",
"label": "WebRTC SFU Sora",
"timestamp": "2024-03-24T07:14:37.423158Z",
"type": "connection.rtc",
"version": "2024.1.0",
"node_name": "sora@192.0.2.1",
"session_id": "FVR7SV953D08ZA0Z3SVCF9HFBR",
"role": "sendrecv",
"channel_id": "sora",
"client_id": "16ZN7HHK5H3PFDFRZCZQN3WVD4",
"bundle_id": "16ZN7HHK5H3PFDFRZCZQN3WVD4",
"multistream": true,
"spotlight": false,
"simulcast": false,
"log_written": true,
"rtc_data": {
"active": true,
"id": "OTdata1A2223648171",
"type": "outbound-rtp",
"kind": "audio",
"ssrc": 2223648171,
"mid": "audio_jDlbho",
"bytesSent": 117003,
"codecId": "COTdata1_109_maxplaybackrate=48000;minptime=10;sprop-stereo=1;stereo=1;usedtx=0;useinbandfec=1",
"headerBytesSent": 1248040,
"mediaSourceId": "SA21",
"mediaType": "audio",
"nackCount": 0,
"packetsSent": 39001,
"remoteId": "RIA2223648171",
"retransmittedBytesSent": 0,
"retransmittedPacketsSent": 0,
"targetBitrate": 64000,
"totalPacketSendDelay": 0.0139959999999999997605,
"transportId": "Tdata1"
},
"rtc_id": "OTdata1A2223648171",
"rtc_timestamp": 1711264477421.78710938,
"rtc_type": "outbound-rtp"
}
{
"connection_id": "16ZN7HHK5H3PFDFRZCZQN3WVD4",
"id": "Z47B1V0DBN7R1AV90HY98CF6Y8",
"label": "WebRTC SFU Sora",
"timestamp": "2024-03-24T07:14:37.423158Z",
"type": "connection.rtc",
"version": "2024.1.0",
"node_name": "sora@192.0.2.1",
"session_id": "FVR7SV953D08ZA0Z3SVCF9HFBR",
"role": "sendrecv",
"channel_id": "sora",
"client_id": "16ZN7HHK5H3PFDFRZCZQN3WVD4",
"multistream": true,
"spotlight": false,
"simulcast": false,
"log_written": true,
"rtc_data": {
"id": "Tdata1",
"type": "transport",
"bytesReceived": 104251,
"bytesSent": 28783357,
"dtlsCipher": "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
"dtlsRole": "client",
"dtlsState": "connected",
"iceLocalUsernameFragment": "90QS",
"iceRole": "controlled",
"iceState": "connected",
"localCertificateId": "CF1F:6E:2B:47:36:FB:64:72:F9:D7:63:C3:16:6D:02:BB:72:62:E9:C0:E1:40:B6:13:E0:90:B2:E5:6C:49:98:6A",
"packetsReceived": 1305,
"packetsSent": 74835,
"remoteCertificateId": "CF0E:AE:2F:F6:0D:EC:07:E4:27:13:34:38:02:EE:BB:EC:07:BA:77:9D:1C:B5:19:93:E0:A2:87:D5:A6:AA:6B:9A",
"selectedCandidatePairChanges": 5,
"selectedCandidatePairId": "CPLE514/b5_sVhdyppm",
"srtpCipher": "AEAD_AES_128_GCM",
"tlsVersion": "FEFD"
},
"rtc_id": "Tdata1",
"rtc_timestamp": 1711264477421.78710938,
"rtc_type": "transport"
}