# ログファイル

**サポート問い合わせの場合は log/ ディレクトリ以下をすべて圧縮して送ってください**

## ログファイル

Sora はデフォルトで log/ ディレクトリ以下にログファイルを出力します。

[log_dir](SORA_CONF.html#ddcdf0) を設定することでログファイルの出力先を変更できます。

### Sora の運用に関係するログ

- sora.jsonl- Sora の開始、終了や問題があった場合に出力されますので、まずはこの監視をお願いします
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- cluster.jsonl- Sora クラスターに関するログが出力されます
  - **Sora クラスターを利用していない場合も出力されます**
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- auth_webhook.jsonl- 認証ウェブフックの送信が **正常に動作した** 処理を書き込みます
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- auth_webhook_error.jsonl- 認証ウェブフックの送信が失敗した処理を書き込みます- レスポンスがステータスコードが 200 番台以外であった場合
    - レスポンスの JSON に `"allowed"` 項目が含まれていない場合
    - レスポンスの JSON が `"allowed": false` にもかかわらず `"reason"` 項目が含まれていない場合
    - 送信先からの応答がなく、タイムアウトした場合
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- session_webhook.jsonl- セッションウェブフックの送信が **正常に動作した** 処理を書き込みます
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- session_webhook_error.jsonl- セッションウェブフックの送信が失敗した処理を書き込みます- レスポンスがステータスコードが 200 番台以外であった場合
    - 送信先からの応答がなく、タイムアウトした場合
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- event_webhook.jsonl- イベントウェブフックで送信した **すべて** の処理を書き込みます
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- event_webhook_error.jsonl- イベントウェブフックの送信が失敗した処理を書き込みます- レスポンスがステータスコードが 200 番台以外であった場合
    - 送信先からの応答がなく、タイムアウトした場合
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- stats_webhook.jsonl- このログは [stats_webhook_log](SORA_CONF.html#2fa540) を `true` に設定した場合に出力されます
  - 統計ウェブフックで送信した **すべて** の処理を書き込みます
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- stats_webhook_error.jsonl- このログは [stats_webhook_log](SORA_CONF.html#2fa540) を `true` に設定した場合に出力されます
  - 統計ウェブフックの送信が失敗した処理を書き込みます- レスポンスがステータスコードが 200 番台以外であった場合
    - 送信先からの応答がなく、タイムアウトした場合
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- rtc_stats.jsonl- このログは [rtc_stats_log](SORA_CONF.html#2fc848) を `true` に設定した場合に出力されます
  - クライアントの RTC 統計情報を出力します
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します

### Sora のサポートに関係するログ

- connection.jsonl- 接続が切断した際にクライアントとサーバーの統計情報を出力するログです
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- signaling.jsonl- シグナリングでやりとりされている offer / answer / candidate / re-offer / re-answer と接続終了 (close) を記録したログです
  - OBS WHIP/WHEP 用の whip-offer / whip-answer / whep-offer / whep-answer も出力します
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- signaling_error.jsonl- シグナリングでエラーが発生した際にエラー情報を出力します
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- api.jsonl- 一部の API 操作に関するログを出力します
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- internal.jsonl- Sora が予定外の動作をしたときに出力されるログです。問題解決に必須のログです
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- crash.log- Sora が予定外の動作をしたときに出力されるログです。問題解決に必須のログです
  - ログローテーションされませんので、ログローテーションをお願いします
  - 週次ログローテーションを推奨します
- erlang.log.<1..5>- サポート時に必要となるログですので、気にする必要はありません
  - 自動でログローテーションされますので、ログローテーションは不要です
  - `bin/sora foreground` コマンドで起動する場合には出力されません
- sysctl.log- 起動時に取得するログで、毎回上書きされます
  - sysctl -a の実行結果を記録します
  - ログローテーションは不要です
- ulimit.log- 起動時に取得するログで、毎回上書きされます
  - ulimit -n の実行結果を記録します
  - ログローテーションは不要です
- run_erl.log- 起動時に出力されるログのため、ほとんどログが出力されることはありません
  - ログローテーションは不要です
  - `bin/sora foreground` コマンドで起動する場合には出力されません

## 特別なログ

Sora が異常終了した際 `erl_crash.dump` というファイルが log/ ディレクトリに生成されます。

こちらは **必ず** 保存し、送っていただけるようお願いいたします。

### 監視用確認目的で erl_crash.dump ログを強制的に出力させる方法

監視を行う際に実際に `erl_crash.dump` を生成したい場合には、 `bin/sora daemon` で起動した上で、
`kill -SIGUSR1` を使用して `run_erl` プロセスを落としてください。

```bash
$ kill -SIGUSR1 <プロセス ID>
```

この方法で log/ ディレクトリに `erl_crash.dump` が生成されます。

## JSONL (JSON Lines) 形式

Sora は一部のログを除いて JSONL 形式でログを出力します。

JSONL の仕様は [JSON Lines](https://jsonlines.org/) に記載されているものに準拠します。

- UTF-8 エンコード
- 改行は `\n`
- 各行は JSON 値
- ファイル拡張子は `jsonl`

### JSONL 形式で出力されるログ

- sora ログ
- cluster ログ
- internal ログ
- api ログ
- signaling ログ
- connection ログ
- auth_webhook ログ
- auth_webhook_error ログ
- session_webhook ログ
- session_webhook_error ログ
- event_webhook ログ
- event_webhook_error ログ
- stats_webhook ログ
- stats_webhook_error ログ

### id

Sora が出力する全ての JSONL 形式のログには UUIDv4 を Base32 でエンコードした `"id"` が含まれます。

`"id": "JKBYVZA3KN6QH249B6QTKDCX8M"`

## auth_webhook ログ

**出力ファイル名**: auth_webhook.jsonl

```javascript
{
  "timestamp": "2024-01-19T02:44:22.799941Z",
  "id": "7N7RTNSEVN43ZB7NVXGAYPETJ4",
  "req": {
    "timestamp": "2024-01-19T02:44:22.793747Z",
    "id": "1EYTQSFVZ56MZ2BRZC12GQYQKW",
    "x_forwarded_for": "49.97.11.19",

    "version": "2024.1.0",
    "label": "WebRTC SFU Sora",
    "node_name": "sora@127.0.0.1",

    "role": "sendrecv",
    "channel_id": "sora",
    "connection_id": "9SRMRSDWA959XFN74DCV3Z6XA0",

    "simulcast": false,
    "spotlight": false,

    "audio": true,
    "audio_codec_type": "OPUS",

    "video": true,
    "video_codec_type": "VP9",
    "video_bit_rate": 500,
    "video_vp9_params": {
      "profile_id": 0
    },

    "data_channel_signaling": true,
    "ignore_disconnect_websocket": false,

    "channel_connections": 0,
    "channel_sendrecv_connections": 0,
    "channel_sendonly_connections": 0,
    "channel_recvonly_connections": 0,

    "sora_client": {
      "raw": "Sora JavaScript SDK 2024.1.0",
      "type": "Sora JavaScript SDK",
      "version": "2024.1.0",
      "environment": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
    },

    "e2ee": false
  },
  "res": {
    "allowed": true,
    "client_id": "client-01"
  },
  "url": "http://192.0.2.1:9000/webhook/auth"
}
```

## auth_webhook_error ログ

**出力ファイル名**: auth_webhook_error.jsonl

認証ウェブフックが正常に動作しなかった場合に出力します。

`auth_webhook` ログとは異なり `res` ではなく `reason` が出力されます。

## session_webhook ログ

**出力ファイル名**: session_webhook.jsonl

レスポンスが返却されない場合、 `res` は出力されません。

```javascript
{
  "id": "XJ227VDDFH60BAB833C1R2HDBW",
  "timestamp": "2024-04-19T05:32:25.583312Z",
  "req": {
    "id": "D5PAF0ZHDX00B4VAWMZAR866MR",
    "label": "WebRTC SFU Sora",
    "timestamp": "2024-04-19T05:32:24.280641Z",
    "type": "session.created",
    "version": "2024.1.0",
    "node_name": "sora@127.0.0.1",
    "session_id": "NAA3DGPJQH2J7FDV698RZ9X6R0",
    "channel_id": "sora",
    "spotlight": false,
    "created_time": 1713504744,
    "created_timestamp": "2024-04-19T05:32:24.277809Z"
  },
  "url": "http://192.0.2.1/webhook/session",
  "res": {
    "recording": true
  }
}
```


## connection ログ

**出力ファイル名**: connection.jsonl

Sora は接続単位で統計情報を保持しています。クライアント側の統計情報とサーバー側の統計情報の両方をログとして出力します。

クライアント側の統計情報は RTC 統計情報機能を利用しているため、
SDK 側が RTC 統計機能に対応している必要があります。

こちらのログはログローテーションしないため、ローテーションが必要となります。


## sora ログ

**出力ファイル名**: sora.jsonl

sora ログは主にサポートで利用するためのログを出力します。そのためエラーメッセージがかなり技術的な表現になっています。

- sora ログは何かあって大量のログが出たとしてもうまい具合にスキップする機能が入っています

### UTC に固定

sora ログのタイムスタンプは RFC 3339 UTC (マイクロ秒) 形式に固定されています。
`timestamp` という項目でタイムスタンプが出力されます。

```javascript
{
  "id": "QGJMC1AF3552V448N8F53CZBJ4",
  "level": "debug",
  "channel_id": "sora",
  "role": "sendonly",
  "simulcast": false,
  "spotlight": false,
  "node_name": "sora@127.0.0.1",
  "connection_id": "NXHKH46FP93571ZM4PZBSFD4Z4",
  "timestamp": "2022-08-02T04:43:02.828358Z"
}
```

### クラスター利用時

```javascript
{
  "id": "QR6YX8VW8H76N6S3B7HBCXJ4PM",
  "level": "debug",
  "channel_id": "sora",
  "role": "sendonly",
  "simulcast": false,
  "spotlight": false,
  "node_name": "sora@127.0.0.1",
  "connection_id": "NXHKH46FP93571ZM4PZBSFD4Z4",
  "timestamp": "2022-08-02T04:43:02.828358Z"
}
```

### オプション情報

```javascript
{
  "level": "debug",
  "channel_id": "sora",
  "role": "sendonly",
  "simulcast": false,
  "spotlight": false,
  "node_name": "sora@127.0.0.1",
  "connection_id": "NXHKH46FP93571ZM4PZBSFD4Z4",
  "timestamp": "2022-08-02T04:43:02.828358Z"
}
```

### 出力例

ライセンスの同時接続数を超えて接続しようとした際に出力される `EXCEED-MAX-CONNECTIONS` の出力例は次の通りです。

```javascript
{
  "id": "JKBYVZA3KN6QH249B6QTKDCX8M",
  "timestamp": "2024-01-19T02:44:22.799941Z",
  "node": "sora@127.0.0.1",
  "level": "error",
  "msg": "EXCEED-MAX-CONNECTIONS | connections=101",
  "domain": [
    "sora",
    "signaling"
  ],
  "channel_id": "sora",
  "role": "recvonly",
  "connection_id": "J9RQEB074S2EB9SFBCN9AH7ASM",
  "simulcast": false,
  "spotlight": false,
  "sora_version": "2024.1.0"
}
```

認証ウェブフック成功時に認証サーバーから払い出された値が不正な場合に出力される `INVALID-AUTHZ-VALUE` の出力例は次の通りです。

```javascript
{
  "id": "7N7RTNSEVN43ZB7NVXGAYPETJ4",
  "timestamp": "2024-01-19T02:44:22.799941Z",
  "node": "sora@127.0.0.1",
  "level": "warning",
  "msg": "INVALID-AUTHZ-VALUE | client_id=12345",
  "domain": [
    "sora",
    "signaling"
  ],
  "channel_id": "sora",
  "role": "sendrecv",
  "connection_id": "9SRMRSDWA959XFN74DCV3Z6XA0",
  "simulcast": false,
  "spotlight": false,
  "sora_version": "2024.1.0"
}
```

DataChannel シグナリングで `ignore_disconnect_websocket: true` の際に WebSocket が想定外の終了をした場合に出力される `WEBSOCKET-TERMINATE` の出力例は次の通りです。

```javascript
{
  "id": "XJ227VDDFH60BAB833C1R2HDBW",
  "timestamp": "2024-04-19T05:32:25.583312Z",
  "node": "sora@127.0.0.1",
  "level": "warning",
  "msg": "WEBSOCKET-TERMINATE | reason={error,closed}, connected=true",
  "domain": [
    "sora",
    "signaling"
  ],
  "channel_id": "sora",
  "role": "sendrecv",
  "connection_id": "174QEZP34D45B6S7665Y32MSQ0",
  "simulcast": false,
  "spotlight": false,
  "sora_version": "2024.1.0"
}
```

### warning


ログレベル `warning` は「接続自体は維持できる問題」の際に出力します。
このログが出力された場合でも Sora 側から切断は行いません。

- 一般- WEBSOCKET-TERMINATE- DataChannel シグナリングで ignore_disconnect_websocket: true の際に WebSocket が想定外の終了をした場合に出力します
  - MULTISTREAM-RE-ANSWER-NO-ICE-UFRAG- マルチストリーム利用時 `type: re-answer` を受信した際に ICE に必要な SDP が含まれていない場合に出力します
  - MULTISTREAM-INTERNAL-ERROR
- ウェブフック- INVALID-AUTHZ-VALUE- 認証ウェブフック成功時に認証サーバーからの払い出した値がおかしい場合に出力します
  - TERMINATE-EVENT-WORKER- イベントウェブフックのワーカーが何らかの理由で終了した場合に出力します
  - MISSING-WEBHOOK-BASIC-AUTH-USER-ID- ウェブフック利用時にベーシック認証のユーザー ID が見つからない場合に出力します
  - MISSING-WEBHOOK-BASIC-AUTH-PASSWORD- ウェブフック利用時にベーシック認証のパスワードが見つからない場合に出力します
  - MISSING-WEBHOOK-PROXY-AUTH-PASSWORD- ウェブフック利用時にプロキシのパスワードが見つからない場合に出力します
- 録画- ARCHIVE-FINAL-SPLIT-ERROR- 録画ファイルの分割がエラーになった場合に出力します、ただし全体出力に向けて処理は継続します
- プロトコル- DTLS-ALERT- DTLS でレベルが WARNING のアラートメッセージがクライアントから送られてきた場合に出力します
  - TURN-SEND-INDICATION-BINDING-ERROR- TURN 利用時に STUN-Binding-Error over STUN-Send-Indication を受信した場合に出力します
  - TURN-CHANNEL-DATA-BINDING-ERROR- TURN 利用時に STUN-Binding-Error over TURN-Channel-Data を受信した場合に出力します
  - SIMULCAST-DUPLICATED-RID- クライアントから複数の SSRC から同一の RID が送られてきた場合に出力します
  - UNKNOWN-RTP- `role: recvonly` にもかかわらず RTP パケットが送られてきた場合に出力します
    - Sora の内部エラーでも出力される場合があります
  - UNKNOWN-RTCP- 見知らぬ RTCP を受信した場合に出力します
  - ULPFEC-RECOVER-ERROR- ULPFEC を利用している場合にリカバーを試みて失敗した場合に出力します
  - RTP-PACKET-LOSS-SIMULATOR-INCOMING-ENABLED- 受信パケロスシュミレーターを有効にしている場合に出力します
  - RTP-PACKET-LOSS-SIMULATOR-OUTGOING-ENABLED- 送信パケロスシュミレーターを有効にしている場合に出力します

### error


ログレベル `error` は「接続自体を維持できない問題」の際に出力します。
このログが出力された場合、Sora 側から切断を行います。

- 一般- UNEXPECTED-EXIT
- シグナリング- INTERNAL-ERROR- Sora の内部エラーです
  - SIGNALING-INTERNAL-ERROR- シグナリングでの内部エラーが発生した場合に出力します
- ライセンス- EXPIRED-LICENSE- ライセンスが切れている場合に出力されます
  - EXCEED-MAX-CONNECTIONS- ライセンスの同時接続数を超えて接続をしようとしたクライアントがいた場合に出力されます
- イベントウェブフック- EVENT-WEBHOOK-ERROR- イベントウェブフックリクエストが正常に送信できなかった場合に出力します
- DataChannel- INVALID-DATA-CHANNEL-USER-DATA- 片方向でしか利用していない DataChannel にメッセージが送られてきた場合に出力します
- 録画- ARCHIVE-FAILED- 録画ファイルの生成に失敗した際に出力します
- プロトコル- TURN-UDP-INTERNAL-ERROR- TURN UDP で内部エラーが発生した場合に出力します
  - DTLS-ALERT- DTLS でレベルが FATAL のアラートメッセージが送られてきたとき出力します

### emergency

ログレベル `emergency` は「Sora の起動を維持できない問題」の際に出力します。
このログが出力された場合、Sora を終了します。

- SORA-NODE-DUPLICATED- 同一ノード名の Sora が既に起動している場合に出力します
  - `src/` 以下の Erlang コードではなく、起動前スクリプト `rel/pkg/pre_start` から `sora.jsonl` に直接書き込まれます
- BOOT-FAILED- Sora が正常に起動できない場合に出力します
- 設定- SORA-CONF-ERROR- sora.conf が正常に読み込めない場合に出力します