# 統計エクスポーター機能

*バージョン 2025.1.0 で削除。*

> **注意**
>
> この機能は 2025 年 6 月リリースの Sora にて廃止しました。

今後は [統計ウェブフック機能](STATS_WEBHOOK.html) をご利用ください。

## 概要

Sora 経由で統計情報コレクターに向けて統計情報をエクスポートする機能です。

## 注意

### IPv6 非対応

現時点で、統計エクスポーターは IPv6 を利用できません。

## HTTP/2

- 統計コレクターサーバーは HTTP/2 に対応している必要があります
- h2c と h2 の両方に対応しています
- `http://` から始めると h2c を利用します
- `https://` から始めると h2 を利用します

## WebRTC Stats Collector Kohaku

**URL**: 

Kohaku は統計エクスポーター対応の統計コレクターです。

## 設定

### stats_collector_url

統計情報を収集するコレクターの URL を指定します。 HTTP または HTTPS の URL が指定できます。

```ini
stats_collector_url = http://192.0.2.10:5890/collector
```

### default_stats_exporter

`stats_collector_url` が指定されていた場合、デフォルトでは統計情報をコレクターに送信します。
もし、統計情報の送信を接続ごとに行いたい場合、この設定を `false` にし、
統計情報を送信したい接続の認証成功時に `"stats_exporter": true` を払い出すようにしてください。

```ini
default_stats_exporter = false
```

### stats_exporter_number

統計情報を出力するエクスポーターの数を指定できます。
基本的にはデフォルトの 5 で足りますが、同時接続数が多い場合は変更をお勧めします。

```ini
stats_exporter_number = 5
```

### stats_exporter_tls_fullchain_file

mTLS を利用するための設定で、中間証明書を含むクライアント証明書を PEM 形式で設定して下さい。

```ini
stats_exporter_tls_fullchain_file = /path/to/fullchain.pem
```

### stats_exporter_tls_privkey_file

統計コレクターサーバーと mTLS を利用するための設定で、クライアント証明書の秘密鍵を PEM 形式で設定して下さい。

> **重要**
>
> 秘密鍵にパスフレーズが設定されている場合はエラーとなります

```ini
stats_exporter_tls_privkey_file = /path/to/privkey.pem
```

### stats_exporter_tls_verify_cacert_file

> **注釈**
>
> CA 証明書を指定しない場合、OS 組み込みの証明書を利用します。詳細は [ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する OS 組み込みのルート CA 証明書について](WEBHOOK.html#e8a845) をご確認ください。

統計コレクターサーバーとの通信に HTTPS を利用した際、サーバー証明書のチェックを行う CA ファイルを PEM 形式で設定して下さい。

```ini
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](https://www.w3.org/TR/webrtc-stats/) に準拠している必要があります。

- type- `connection.user-agent`
- channel_id- チャネル ID が入ります
- role
- session_id- セッション ID が入ります
- client_id
- connection_id
- simulcast
- spotlight
- stats

```javascript
{
  "channel_id": "sora",
  "session_id": "78K3N8E5M551XEKEWR8QN77PHW",
  "client_id": "NCD5EF3ME900ZDJ3SE27Y6AB6R",
  "connection_id": "NCD5EF3ME900ZDJ3SE27Y6AB6R",
  "id": "N6W0DBF6A957B01BKNJJR1HC04",
  "label": "WebRTC SFU Sora",
  "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 シグナリング利用時

```mermaid
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
```