# ログトレース

EMQX 5.0では、特定のクライアントID、トピック、IPアドレス、またはルールIDに対してリアルタイムでデバッグレベルのログ出力を可能にするログトレース機能を導入しました。これにより、過剰なログによるシステムパフォーマンスへの影響を抑えつつ、本番環境での詳細なデバッグが可能となり、EMQXの問題診断と解決の効率が向上します。

## ログトレースの仕組み

ログトレース機能は、組み込みのErlang Logger Filter関数を利用して実装されており、全体のメッセージスループットへの影響はほとんどありません。EMQXは独立したファイルハンドラーを使用してトレースのディスクログを永続化し、各クライアント接続ごとに別プロセスを生成してそのメッセージを処理します。

クライアントがメッセージを送信すると、その接続を担当する独立プロセスはまずカスタマイズされたトレースフィルターのルールにメッセージが合致するかを確認します。例えば、指定されたクライアントIDからのメッセージかどうかをチェックします。

- 指定されたクライアントIDからのメッセージであれば、そのメッセージをバイナリデータに変換し、非同期で該当するファイルハンドラーに送信します。  
- 指定されたクライアントIDでなければ、EMQXは元の転送ロジックを実行します。

ファイルハンドラーはバイナリデータをトレースファイルとしてディスクに永続化する役割を担います。

## ログトレースを使う理由

ログトレース機能は、本番環境でのデバッグや監視に効果的な以下の主要な利点を提供します。

- **安全性**：フィルタリング処理は各クライアントごとに独立して行われるため、ファイルハンドラーが大量のメッセージで過負荷になることを防ぎます。ほとんどのログはフィルタリングされるため、本番環境でも安全に利用できます。  
- **信頼性**：トレースログがEMQX全体のメッセージスループットに影響を与えず、ログデータの保存と取得を信頼性高く効率的に行えます。  
- **機動性**：異常メッセージやデータロス、クライアント切断、サブスクリプション失敗など様々なシナリオで利用可能です。特定時間に発生したシステム障害に対しては、タスクの開始・停止時間を設定して自動的にログ収集できるため非常に便利です。

## ログトレースの作成

このセクションでは、ダッシュボードでログトレースルールを作成する方法を説明します。クライアントID、トピック、IPアドレス、またはルールIDに基づいてトレースできます。

1. 左側のナビゲーションメニューで **Diagnose** -> **Log Trace** をクリックします。  
2. **Log Trace** ページで **Create** をクリックしてトレースルールを設定します。

### 共通トレースオプションの設定

**Create Trace** ダイアログで、すべてのトレースタイプに共通する以下のオプションを設定します。

- **Name**：ログ内で識別しやすい説明的な名前を入力します。この名前はトレース一覧に表示され、トレースの種類（例：「Client ID Trace」や「Topic Trace」）などの有用なコンテキストを含めることで検索や識別が容易になります。  
- **Start Time / End Time**：トレースの開始時間と終了時間を選択します。開始時間が現在時刻より過去または同時の場合は、現在時刻からトレースが開始されます。  
- **Formatter**：ログ出力のフォーマットを指定します。`JSON` または `Text` が選択可能です。  
- **Payload Encode**：トレースログファイル内のペイロードのエンコード形式を指定します。以下のいずれかを選択してください。  
  - `Text`：テキストベースまたはプレーンテキストプロトコル。JSONエンコードされたペイロードに推奨されます。  
  - `HEX`：バイナリの16進数エンコード。カスタムバイナリプロトコルに推奨されます。  
  - `Hidden`：ペイロードを `******` としてマスク（機密情報の隠蔽に有用）。  
- **Payload Limit**：トレースファイルに出力するペイロードの最大バイト数を設定します。このオプションは **Payload Encode** が `Text` または `HEX` の場合にのみ有効です。ペイロードが制限を超える場合は切り詰められます。デフォルトは `1024 B` です。無効にするとペイロードサイズに制限はかかりません。デフォルトで有効です。

### クライアントIDによるトレース

1. Create Traceダイアログで、**Type** ドロップダウンリストから `Client ID` を選択します。  
2. トレース対象のクライアントIDを入力します。  
3. 共通オプションを設定します。詳細は[共通トレースオプションの設定](#共通トレースオプションの設定)を参照してください。  
4. **Create** をクリックして完了します。

指定されたクライアントIDのEMQX接続に関するインタラクションがログトレースに含まれます。

### トピックによるトレース

1. Create Traceダイアログで、**Type** ドロップダウンリストから `Topic` を選択します。  
2. トレース対象のトピックを入力します。ワイルドカード文字もサポートしています（例：`/pay/#`）。  
3. 共通オプションを設定します。詳細は[共通トレースオプションの設定](#共通トレースオプションの設定)を参照してください。  
4. **Create** をクリックして完了します。

指定されたトピックのパブリッシュ、サブスクライブ、サブスクリプション解除に関する情報がログトレースに含まれます。

### IPアドレスによるトレース

1. Create Traceダイアログで、**Type** ドロップダウンリストから `IP Address` を選択します。  
2. トレース対象のIPアドレスを入力します（例：`192.168.0.5`）。  
3. 共通オプションを設定します。詳細は[共通トレースオプションの設定](#共通トレースオプションの設定)を参照してください。  
4. **Create** をクリックして完了します。

指定されたIPアドレスのEMQX接続に関するインタラクションがログトレースに含まれます。

### ルールIDによるトレース

1. Create Traceダイアログで、**Type** ドロップダウンリストから `Rule ID` を選択します。  
2. トレース対象のルールIDを入力します。ルールIDは **Integration** -> **Rules** ページで確認できます。  
3. 共通オプションを設定します。詳細は[共通トレースオプションの設定](#共通トレースオプションの設定)を参照してください。  
4. **Create** をクリックして完了します。

トレース結果にはルールSQLの実行結果およびルールに追加されたすべてのアクションの実行ログが含まれ、ルールのデバッグや最適化に役立ちます。

[Test Rules](../data-integration/rule-get-started.md#test-rules) 操作では、このトレースタイプを自動的に作成・管理できます。ルールをテストすると、EMQXは自動的にトレースタスクを生成し、テスト終了後に自動削除します。

## ログトレースの確認

作成されたトレースレコードが一覧表示されます。最大で30件のトレースログを作成可能です。リストに表示されるログファイルサイズは非圧縮ファイルサイズの合計です。**Stop** ボタンをクリックすると手動でログ記録を停止できます。または指定した終了時間まで待機します。

特定のトレースレコード名をクリックすると、異なるノードでログのダウンロードを選択できます。

<img src="./assets/log-trace-node-ee.png" alt="ログトレースノード" style="zoom:50%;" />

トレースログはノードごとに最大512MBまで保存可能です。生成されたログファイルが最大容量に達すると、それ以上のログ追記を停止し、プライマリログファイルにアラートを出します。ダッシュボードからのダウンロードがタイムアウトした場合は、サーバーの `/data/trace` ディレクトリにログファイルが保存されているのでそちらをご確認ください。EMQXクラスターを再起動すると、未完了のログトレースは再開されます。