# ログトレース

ログトレースは、EMQX Cloudのデプロイメントにおいて、特定のMQTTクライアント、トピック、送信元IPアドレス、またはルールIDに対するデバッグレベルのログを収集するために使用します。ログトレースは、クライアントの接続失敗、予期しない切断、サブスクライブ失敗、メッセージのパブリッシュ問題、メッセージの損失、ルール実行エラーなどのトラブルシューティングに役立ちます。全デプロイメントで詳細ログを有効にする必要がない場合に特に有効です。

## 利用可能環境と制限

ログトレースは、EMQX v6.1.3以降を実行している専用および専用Flexデプロイメントでのみ利用可能です。これらの条件を満たさない場合、EMQX Cloudコンソールの**Diagnostics**メニュー内に**Trace**が表示されません。

ログトレースの制限は以下の通りです。

- 1つのデプロイメントにつき最大10個のトレースを作成可能です。
- 各トレースは最大24時間まで実行できます。
- トレース名は英字で始まり、英数字、アンダースコア（`_`）、ハイフン（`-`）を含めることができます。最大長は256文字です。
- ペイロードの上限は最大1MBまで設定可能です。デフォルトは1024バイトです。

## ログトレースを使うタイミング

特定のトラブルシューティング対象のブローカー側処理を詳細に調査したい場合にログトレースを使用します。典型的なシナリオは以下の通りです。

- クライアントが接続できない、予期せず切断される、認証に失敗する。
- クライアントがトピックにパブリッシュまたはサブスクライブできない。
- メッセージがパブリッシュされているが期待通りに受信されない。
- ルールが期待通りにメッセージを処理しない。
- 複数ノードのデプロイメントで異なるブローカーノードのログを比較したい。

一般的なデプロイメントのエラーや警告は**Diagnostics** -> **Logs**を使用し、特定のクライアント、トピック、IPアドレス、ルールに絞った詳細なトレースが必要な場合にログトレースを利用してください。

## トレースの作成方法

1. EMQX Cloudコンソールで対象のデプロイメントにアクセスします。

2. デプロイメントメニューから**Diagnostics** -> **Trace**を選択します。

3. **Trace**ページで**New**をクリックします。

4. **New Trace**ダイアログで以下の項目を設定します。

   | 項目 | 説明 |
   | --- | --- |
   | **Name** | トレースの名前を入力します。トラブルシューティング対象が識別しやすい名前を使用してください。 |
   | **Type** | トレース条件のタイプを選択します。サポートされているタイプは**Client ID**、**Topic**、**IP Address**、**Rule ID**です。 |
   | **Client ID** / **Topic** / **IP Address** / **Rule ID** | トレース対象の値を入力します。選択した**Type**に応じてラベルが変わります。 |
   | **Time Range** | トレースの開始時刻と終了時刻を選択します。最大24時間まで設定可能です。 |
   | **Payload Encode** | トレースログにメッセージペイロードをどのように記録するかを選択します。 |
   | **Payload Limit** | トレースログに記録するペイロードの最大バイト数を設定します。超過した場合はEMQX Cloudが切り詰めます。 |

5. **Confirm**をクリックします。

EMQX Cloudは設定した開始時刻にトレースを開始し、終了時刻に自動停止します。トレースリストから手動で実行中のトレースを停止することも可能です。

::: tip

問題を再現する前に開始時刻を設定し、できるだけ短い時間範囲を指定してください。ログサイズが小さくなり、トレースの確認が容易になります。

:::

## トレースの種類

以下の条件タイプに基づいてトレースを作成できます。

- **Client ID**：特定のMQTTクライアントに対するブローカーのやり取りをキャプチャします。
- **Topic**：特定のトピックに対するパブリッシュ、サブスクライブ、サブスクライブ解除のイベントをキャプチャします。トピックワイルドカードもサポートします。
- **IP Address**：特定の送信元IPアドレスから接続するクライアントのブローカーとのやり取りをキャプチャします。
- **Rule ID**：特定のルールに対するルール実行ログをキャプチャします。SQL実行やアクション実行の詳細も含みます。

## ペイロードエンコードオプション

**Payload Encode**はトレースログにメッセージペイロードをどのように記録するかを制御します。

- **Text**：ペイロードをテキストとして記録します。プレーンテキストやJSONエンコードされたペイロードに推奨されます。
- **HEX**：ペイロードを16進数で記録します。カスタムバイナリプロトコルに推奨されます。
- **Hidden**：ペイロードを`******`でマスクします。ペイロードに機密情報が含まれる場合に使用してください。

**Payload Limit**は**Text**または**HEX**を選択した場合にのみ適用されます。ペイロードが設定した上限を超えた場合、EMQX Cloudは許可されたバイト数のみをトレースログに書き込みます。

## トレースの表示と管理

**Trace**ページにはデプロイメントで作成された全トレースが一覧表示されます。リストには以下の情報が含まれます。

- **Name**：トレース名。クリックするとトレース詳細が開きます。
- **Type**：トレース条件タイプ。
- **Condition**：トレース対象の値（クライアントID、トピック、IPアドレス、ルールIDなど）。
- **Time Range**：トレースの開始・終了時刻。
- **Status**：トレースの状態（**Running**や**Stopped**など）。
- **Payload Encode**：選択されたペイロードエンコード方式。
- **Payload Limit**：設定されたペイロードサイズ上限。
- **Log Size**：収集されたトレースログのサイズ。
- **Actions**：トレースのダウンロード、停止、削除などの操作。

トレースリストの操作方法：

- トレース名をクリックして詳細を表示。
- ダウンロードアイコンをクリックしてトレースログをダウンロード。
- 停止アイコンをクリックして実行中のトレースを終了。
- 削除アイコンをクリックして不要な停止済みトレースを削除。

実行中のトレースは停止やダウンロードが可能で、停止済みトレースはダウンロードや削除が可能です。

![トレースリスト](./_assets/log_trace_list.png)

## トレース詳細の表示

トレース名をクリックするとトレース詳細ページが開きます。

トレース詳細ページでは、収集されたトレースログがログビューアに表示されます。各ログ行には、タイムスタンプ、プロトコルやモジュールのタグ、クライアント識別子、送信元アドレス、パケットタイプ、トピック、認証結果、認可結果、ルール実行の詳細など、トレース対象のアクティビティに応じた情報が含まれます。

デプロイメントに複数のブローカーノードがある場合、トレース詳細ページにはノードセレクターが表示されます。デフォルトでは最も最近トレースログを生成したノードが選択されますが、手動で別のノードを選択してそのノードのログを閲覧できます。

トレース詳細ページの操作：

- 表示中のトレースログを更新（リフレッシュ）。
- 選択したノードのトレースログをダウンロード。
- 複数ノードがある場合、ノードを切り替えてログを確認。

## デモ：テストMQTTクライアントのトレース

このデモでは、テストクライアントのトレースを作成し、組み込みのMQTTクライアントでMQTTトラフィックを生成し、トレースログを確認する手順を示します。

### ステップ1：Client IDトレースの作成

1. **Diagnostics** -> **Trace**に移動します。

2. **New**をクリックします。

3. 以下の値でトレースを設定します。

   | 項目 | 値 |
   | --- | --- |
   | **Name** | `client_trace_test` |
   | **Type** | `Client ID` |
   | **Client ID** | `trace_client_001` |
   | **Time Range** | 約30分の時間範囲を選択 |
   | **Payload Encode** | `Text` |
   | **Payload Limit** | `1024 B` または `1 KB` |

4. **Confirm**をクリックします。

トレースがトレースリストに表示され、選択した時間範囲内は**Running**状態になります。

### ステップ2：テストトラフィックの生成とトレースログの発生

**Diagnostics** -> **MQTT Client**の組み込みMQTTクライアントを使い、外部MQTTクライアントを使わずにログトレース用のトラフィックを生成します。

1. **Diagnostics** -> **MQTT Client**に移動します。

2. 以下のいずれかの方法でデプロイメントに接続します。

   - **Connect with Auto-Generated Authentication**：利用可能なら迅速なテストに推奨。
   - **Connect with Added Authentication**：**Access Control** -> **Authentication**で設定済みのユーザー名とパスワードを使用。

3. MQTTクライアントのクライアントIDが以下と一致していることを確認します。

   ```text
   trace_client_001
   ```

   トレース条件のクライアントIDと同じである必要があります。

4. **Messages**エリアで以下の値でテストメッセージをパブリッシュします。

   | 項目 | 値 |
   | --- | --- |
   | **Topic** | `trace/test` |
   | **QoS** | `QoS 0` |
   | **Payload Format** | `JSON` |
   | **Payload** | `{ "message": "hello" }` |

5. **Publish**をクリックします。複数回パブリッシュして追加のトレースログを生成可能です。

   MQTTクライアントページには接続状態、パブリッシュトピック、ペイロード、送信済みメッセージが表示されます。

   ![ログトレース用のテストトラフィックを生成するMQTTクライアント](./_assets/log_trace_mqtt_client_demo.png)

### ステップ3：トレースログの確認

1. **Diagnostics** -> **Trace**に戻ります。

2. トレースリストで`client_trace_test`トレースを確認します。

   - トレースがまだ時間範囲内であれば**Status**が**Running**であることを確認。
   - 対象クライアントがトラフィックを生成すると**Log Size**が増加することを確認。

   ![MQTTクライアントパネル付きのトレースリスト](./_assets/log_trace_demo_trace_list.png)

   トレースログを確認する間はMQTTクライアントパネルを開いたままにしてください。テストクライアントを停止する場合は**Disconnect**をクリックし、異なるクライアントIDで再接続する場合は**Edit**をクリックして設定を更新します。

3. `client_trace_test`をクリックしてトレース詳細を開きます。

4. トレースログを確認します。このデモでは以下のようなログが含まれる可能性があります。

   - `CONNECT`、`CONNACK`などのMQTT接続パケット。
   - `trace/test`への`PUBLISH`パケットなどのパブリッシュメッセージ。
   - 認証および認可の結果。
   - `PINGREQ`、`PINGRESP`などのキープアライブパケット。

5. デプロイメントに複数のブローカーノードがある場合はノードセレクターを使ってノードを切り替え、特定ノードのログを閲覧します。

6. リフレッシュアイコンをクリックして表示ログを更新、またはダウンロードアイコンをクリックしてトレースログをダウンロードします。

テスト終了後はトレースリストに戻り、まだ実行中であればトレースを停止してください。必要なログをダウンロードした後、不要な停止済みトレースは削除可能です。

## ベストプラクティス

- ログ量を減らすために可能な限り狭いトレース条件を使用してください。
- 問題を再現する際は短い時間範囲を設定してください。
- ペイロードに機密情報が含まれる可能性がある場合は**Payload Encode**に**Hidden**を使用してください。
- 大きなペイロードを調査する必要がある場合のみ**Payload Limit**を増やしてください。
- 不要になったトレースは停止または削除してください。