ログトレース
EMQX 5.0では、特定のクライアントID、トピック、IPアドレス、またはルールIDに対してリアルタイムのデバッグレベルログ出力を可能にするログトレース機能を導入しました。これにより、過剰なログによるシステムパフォーマンスへの影響を抑えつつ、本番環境での詳細なデバッグが可能となり、EMQXの問題診断と解決の効率が向上します。
ログトレースの仕組み
ログトレース機能は、Erlang組み込みのLogger Filter機能を利用して実装されており、全体のメッセージスループットへの影響はほとんどありません。EMQXは独立したファイルハンドラーを使用してトレースログを永続化し、各クライアント接続ごとに別プロセスを生成してそのメッセージを処理します。
クライアントがメッセージを送信すると、その接続を担当するプロセスはメッセージがトレースフィルターのルールに合致するかどうかを確認します。例えば、指定されたクライアントIDからのメッセージかどうかをチェックします。
- メッセージがフィルター条件に合致する場合、プロセスはそれを人間が読みやすいトレースイベントに変換し、非同期で該当するファイルハンドラーに送信します。
- それ以外の場合は、通常通りメッセージを処理します。
ファイルハンドラーはトレースイベントをそれぞれのトレースファイルにディスク上で永続化する役割を担います。
ノードまたはEMQXクラスター全体が再起動された場合でも、未完了のログトレースは自動的に再開されます。
ログトレースを使う理由
ログトレース機能は、本番環境でのデバッグおよび監視において以下の主要な理由から効果的なツールです。
- 安全性：フィルタリング処理は各クライアントごとに独立して行われるため、ファイルハンドラーの過負荷を防ぎます。ほとんどのログはフィルタリングされるため、本番環境でも安全に利用できます。
- 信頼性：トレースログがEMQX全体のメッセージスループットに影響を与えず、ログデータの保存と取得を信頼性高く効率的に行えます。
- 機動性：メッセージやデータ損失のデバッグ、クライアント切断、サブスクリプション失敗など様々なシナリオで利用可能です。特定の時間に発生した問題に対しては、トレースの開始・停止を自動でスケジュールしてログ収集を便利に行えます。
ログトレースの作成
このセクションでは、ダッシュボードからログトレースルールを作成する方法を説明します。クライアントID、トピック、IPアドレス、またはルールIDに基づいてトレースを行えます。
- 左側のナビゲーションメニューで Diagnose -> Log Traces をクリックします。
- Log Traces ページで Create をクリックしてトレースルールを設定します。
共通トレースオプションの設定
トレース作成 ダイアログで、すべてのトレースタイプに共通する以下のオプションを設定します。
- 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によるトレース
- Create Trace ダイアログで、Type ドロップダウンリストから
Client IDを選択します。 - トレース対象のクライアントIDを入力します。
- 共通トレースオプションの設定に従ってオプションを設定します。
- Create をクリックします。
指定したクライアントIDとEMQXブローカー間のやり取りをログトレースでキャプチャします。
トピックによるトレース
- Create Trace ダイアログで、Type ドロップダウンリストから
Topicを選択します。 - トレース対象のトピックを入力します。ワイルドカードもサポートされています。例：
/pay/# - 共通トレースオプションの設定に従ってオプションを設定します。
- Create をクリックします。
指定したトピックにパブリッシュされたメッセージや、サブスクライブおよびサブスクリプション解除イベントをキャプチャします。
IPアドレスによるトレース
- Create Trace ダイアログで、Type ドロップダウンリストから
IP Addressを選択します。 - トレース対象のIPアドレスを入力します。例：
192.168.0.5 - 共通トレースオプションの設定に従ってオプションを設定します。
- Create をクリックします。
指定したIPアドレスから接続するクライアントとEMQXブローカー間のやり取りをキャプチャします。
ルールIDによるトレース
- Create Trace ダイアログで、Type ドロップダウンリストから
Rule IDを選択します。 - トレース対象のルールIDを入力します。ルールIDは Integration -> Rules ページで確認できます。
- 共通トレースオプションの設定に従ってオプションを設定します。
- Create をクリックします。
トレース結果にはルールSQLの実行結果と、ルールに追加されたすべてのアクションの実行ログが含まれ、ルールのデバッグや最適化に役立ちます。
テストルール 操作では、このトレースタイプを自動的に作成・管理できます。ルールをテストすると、EMQXは自動的にトレースタスクを生成し、テスト終了後に自動で削除します。
ログトレースの閲覧
作成したログトレースは Log Trace ページに一覧表示されます。リストに表示されるログファイルサイズは非圧縮ファイルサイズの合計です。トレースは手動で Stop ボタンをクリックして停止できますが、指定した終了時刻に達すると自動で停止します。
作成できるトレース数には上限があります。デフォルトでは30件ですが、trace.max_traces パラメータで変更可能です。
トレース名をクリックすると詳細画面が開き、トレースイベントの閲覧やクラスター内の特定ノードからログのダウンロードが可能です。
デフォルトでは、各トレースはノードごとに最大128MBのログデータに制限されています。この制限は trace.max_file_size 設定パラメータで変更可能です。ディスク容量管理のため、ファイルハンドラーはローテーション動作を行い、トレースログがサイズ制限に達すると古いトレースイベントから順に破棄して新しいイベントのための空きを確保します。これは厳密な上限ではなく、ログファイルの合計サイズは通常設定値より小さいですが、一時的に数キロバイト程度超過することがあります。
ダッシュボードからのダウンロードがタイムアウトした場合は、各EMQXノードの /data/trace ディレクトリから手動でトレースログを取得できます。