ログトレース

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

ログトレースの仕組み

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

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

• メッセージがフィルター条件に合致する場合、プロセスはそれを人間が読みやすいトレースイベントに変換し、非同期で該当するファイルハンドラーに送信します。
• それ以外の場合は、通常通りメッセージを処理します。

ファイルハンドラーはトレースイベントをそれぞれのトレースファイルにディスク上で永続化する役割を担います。

ノードまたはEMQXクラスター全体が再起動された場合、未完了のログトレースは自動的に再開されます。

ログトレースを使う理由

ログトレース機能は、本番環境でのデバッグや監視において以下の重要な理由から効果的なツールです。

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

ログトレースのネームスペーススコープ

EMQX 6.0.3以降、ネームスペース付きロールを使用している場合、ログトレースへのアクセスはネームスペース単位でスコープされます。

• ネームスペース付きユーザーは、GET /trace のレスポンスで自分のネームスペースに属するトレースのみを閲覧できます。
• 以下のトレース単位操作は、トレースが異なるネームスペースに属する場合に 404 Not Found を返し、クロスネームスペースのトレース存在を漏らしません。
  • PUT /trace/:name/stop
  • GET /trace/:name/download
  • GET /trace/:name/log
  • GET /trace/:name/log_detail
  • DELETE /trace/:name
• 一括削除操作（DELETE /trace）はグローバル管理者のみが実行可能で、ネームスペース付きユーザーは 403 Forbidden を受け取ります。

グローバル管理者はネームスペースに関係なくすべてのトレースを閲覧・管理できます。

ログトレースの作成

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

1. 左側のナビゲーションメニューで 診断 -> ログトレース をクリックします。
2. ログトレース ページで 作成 をクリックし、トレースルールを設定します。

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

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

• 名前：トレースを識別するための説明的な名前を入力します。この名前はトレース一覧に表示され、検索や識別を容易にするために「Client IDトレース」や「Topicトレース」などトレースの種類が分かる名称が望ましいです。
• 開始時間 / 終了時間：トレースの開始・終了時間を選択します。開始時間が過去の場合は即時にトレースが開始されます。
• フォーマッター：ログ出力のフォーマットを指定します。JSON または Text から選択可能です。
• ペイロードエンコード：トレースログ内のメッセージペイロードの形式を指定します。以下から選択します。
  • Text：プレーンテキスト。JSONエンコードされたペイロードに推奨されます。
  • HEX：16進数エンコード。カスタムバイナリプロトコルに推奨されます。
  • Hidden：ペイロードを ****** のようにマスクし、機密情報の隠蔽に有用です。
• ペイロード制限：トレースファイルに出力するペイロードの最大バイト数を設定します。このオプションは ペイロードエンコード が Text または HEX の場合にのみ有効です。制限を超えた場合は切り詰められます。デフォルトは 1024 B で、有効になっていますが無制限にすることも可能です。

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

1. トレース作成ダイアログで、タイプのドロップダウンリストから Client ID を選択します。
2. トレース対象のクライアントIDを入力します。
3. 共通トレースオプションの設定に従いオプションを設定します。
4. 作成をクリックします。

指定したクライアントIDとEMQXブローカー間のやり取りがログトレースされます。

トピックによるトレース

1. トレース作成ダイアログで、タイプのドロップダウンリストから Topic を選択します。
2. トレース対象のトピックを入力します。ワイルドカードもサポートされており、例：/pay/# などが指定可能です。
3. 共通トレースオプションの設定に従いオプションを設定します。
4. 作成をクリックします。

指定したトピックにパブリッシュされたメッセージや、サブスクライブ・サブスクリプション解除のイベントがログトレースされます。

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

1. トレース作成ダイアログで、タイプのドロップダウンリストから IP Address を選択します。
2. トレース対象のIPアドレスを入力します。例：192.168.0.5
3. 共通トレースオプションの設定に従いオプションを設定します。
4. 作成をクリックします。

指定したIPアドレスから接続するクライアントとEMQXブローカー間のやり取りがログトレースされます。

ルールIDによるトレース

1. トレース作成ダイアログで、タイプのドロップダウンリストから Rule ID を選択します。
2. トレース対象のルールIDを入力します。ルールIDは データ統合 -> ルール ページで確認できます。
3. 共通トレースオプションの設定に従いオプションを設定します。
4. 作成をクリックします。

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

ルールのテスト操作では、このトレースタイプを自動的に作成・管理します。ルールのテスト時にEMQXが自動でトレースタスクを生成し、テスト停止後に自動削除します。

ログトレースの閲覧

作成したログトレースは ログトレース ページに一覧表示されます。リストに表示されるログファイルサイズは非圧縮ファイルサイズの合計です。トレースは手動で 停止 ボタンをクリックして停止できますが、指定した終了時間に達すると自動的に停止します。

作成可能なトレース数には制限があり、デフォルトは30ですが、trace.max_traces パラメータで変更可能です。

トレース名をクリックすると詳細画面が開き、トレースイベントの閲覧やクラスター内の特定ノードからログのダウンロードが可能です。

デフォルトでは、各トレースはノードごとに最大128MBのログデータに制限されています。この制限は trace.max_file_size 設定パラメータで変更可能です。ディスク容量管理のため、ファイルハンドラーはローテーション動作を行い、トレースログがサイズ制限に達すると古いトレースイベントから順に破棄して新しいイベントの領域を確保します。これは厳密な上限ではなく、ログファイルの合計サイズは通常設定値より小さいですが、数キロバイト程度一時的に超過することがあります。

ダッシュボードからのダウンロードがタイムアウトした場合は、各EMQXノードの /data/trace ディレクトリから手動でトレースログを取得できます。