ログトレース

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 Trace」や「Topic Trace」）など、検索や識別に役立つ情報を含めることを推奨します。
• 開始時間 / 終了時間：トレースの開始および終了時刻を選択します。開始時間が過去の場合は即時にトレースが開始されます。
• フォーマッター：ログ出力のフォーマットを指定します。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 ディレクトリから手動でトレースログを取得できます。