統計ウェブフック¶

注意

この機能を利用する場合は事前にサポートまでご連絡ください

警告

この機能は実験的機能のため、正式版では仕様が変更される可能性があります

概要¶

統計情報をウェブフックで送信する機能です。

注意¶

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" 項目として送信されます。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    note over C,S: WebRTC 確立
    S-)C: "type": "ping"<br>WebSocket
    C-)S: "type": "pong"<br>WebSocket

    S-)C: "type": "ping"<br>"stats": true<br>WebSocket
    C-)S: "type": "pong"<br>"stats": ...<br>WebSocket
    S->>+A: Stats over HTTP/1.1
    A->>-S: 200 OK
    note over C,S: 60 秒経過
    S-)C: "type": "ping"<br>"stats": true<br>WebSocket
    C-)S: "type": "pong"<br>"stats": ...<br>WebSocket
    S->>+A: Stats over HTTP/1.1
    A->>-S: 200 OK

DataChannel シグナリングを利用している場合¶

data_channel_stats_timer_interval に指定した間隔になります。

DataChannel シグナリングの場合は stats ラベルを利用して、 "type": "req-stats" を送ってクライアントへ統計情報を要求します。

クライアントは stats ラベルを利用して、 "type": "stats" で "reports" に統計情報を含めて送ります。この "reports" が統計ウェブフックの "stats" 項目として送信されます。

        sequenceDiagram
    participant C as クライアント
    participant S as Sora
    participant A as アプリケーションサーバー
    note over C,S: WebRTC 確立
    S-)C: "type": "stats-req"<br>DataChannel
    C-)S: "type": "stats"<br>DataChannel
    S->>+A: Stats over HTTP/1.1
    A->>-S: 200 OK
    note over C,S: 60 秒経過
    S-)C: "type": "stats-req"<br>DataChannel
    C-)S: "type": "stats"<br>DataChannel
    S->>+A: Stats over HTTP/1.1
    A->>-S: 200 OK

設定¶

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": "[email protected]",
  "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 が浮動小数点で入ります
- https://www.w3.org/TR/webrtc-stats/#dom-rtcstats-timestamp
rtc_type
- RTCStats の type が文字列で入ります
- https://www.w3.org/TR/webrtc-stats/#dom-rtcstats-type
rtc_id
- RTCStats の id が文字列で入ります
- https://www.w3.org/TR/webrtc-stats/#dom-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": "[email protected]",
   "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": "[email protected]",
   "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"
}