ログ

ログはトラブルシューティングやシステムパフォーマンスの最適化において信頼できる情報源を提供します。EMQXのログからアクセス状況、動作状況、ネットワークの問題に関する記録を確認できます。

EMQXはコンソールログとファイルログの両方をサポートしています。ログデータの出力方法は2種類あり、必要に応じて出力方法を選択するか、両方を有効にすることも可能です。コンソールログはログデータをコンソールやコマンドラインインターフェースに出力することを指し、開発やデバッグ時にリアルタイムでログを素早く確認できるため一般的に利用されます。ファイルログはログデータをファイルに出力するもので、分析やトラブルシューティングのためにログデータを長期間保存する必要がある本番環境でよく使われます。

システムのデフォルトログ出力は環境変数 EMQX_DEFAULT_LOG_HANDLER により設定可能で、以下の設定を受け付けます。

file: ログ出力をファイルに向ける
console: ログ出力をコンソールに向ける

環境変数 EMQX_DEFAULT_LOG_HANDLER のデフォルトは console ですが、systemdの emqx.service ファイル経由でEMQXを起動すると明示的に file に設定されます。

ログデータが多すぎる場合やログ書き込みが遅い場合など、ログがシステム運用に与える影響を最小限に抑えるため、EMQXはデフォルトでオーバーロード保護機構を有効にし、ユーザーにより良いサービスを提供しています。

ログレベル

EMQXのログレベルは8段階中6段階をサポートしており（RFC 5424準拠）、デフォルトは warning です。低い順に以下のレベルがあります。

bash

debug < info < notice < warning < error < critical

以下の表は各ログレベルの意味と出力内容の例を示しています。

ログレベル	意味	出力例
debug	プログラム内部の詳細情報で、コードのデバッグや診断に役立ちます。本番環境で直接このレベルのログを出力することは推奨されません。代わりに特定のクライアントに対してLog Traceを有効にしてください。	変数の値、関数呼び出しスタックなどの詳細なデバッグ情報。
info	debugレベルより一般的な有用情報。	認証拒否などの軽微な異常や、設定変更の成功など管理操作の結果。
notice	イベント発生を示す重要なシステム情報で、特に対応は不要。	ダッシュボードやCLIからの要求によるコンポーネントの再起動。
warning	対応が必要な潜在的な問題やエラー。通常は重大問題になる前の監視や検出に使われます。	切断、接続タイムアウト、認証失敗などのイベント。
error	エラー発生を示し、管理者が迅速に検出・対応できるようにします。	外部データベースへの接続失敗、存在しないトピックのサブスクライブ失敗、設定ファイルの解析失敗など。
critical	システムクラッシュや機能停止を引き起こす重大なエラー。管理者が即時対応すべき問題を示します。	設定ミスによりコンポーネントが起動・正常動作できない場合。

重要なお知らせ

接続およびパーサーエラーのログに含まれる生のMQTTパケットデータはデフォルトでマスクされています。トラブルシューティングのために一時的に生パケットデータをログに記録したい場合は、リスナーの allow_log_packet_data_from オプションに信頼できるクライアントのIPアドレスまたはCIDR範囲を追加してください。このオプションは信頼できるクライアントに対してのみ、かつ診断時のみ有効にしてください。生パケットデータには認証情報などの機密情報が含まれる可能性があります。

ダッシュボードによるログ設定

このセクションでは主にEMQXダッシュボードを使ったログ設定方法を説明します。設定変更はノードの再起動なしに即時反映されます。

EMQXダッシュボードにアクセスし、左側のナビゲーションメニューから Management -> Logging をクリックします。コンソールログまたはファイルログの設定はそれぞれ対応するタブを選択してください。

コンソールログの設定

Logging ページで Console Log タブを選択します。

コンソールログ出力の設定項目は以下の通りです。

Enable Log Output: トグルスイッチをクリックしてコンソールログ出力を有効化します。
Log Level: 記録する最低ログレベルを選択します。選択肢は debug, info, notice, warning, error, critical, alert, emergency です。デフォルトは warning です。
Log Formatter: ログのフォーマットを選択します。text（自由形式テキスト）または json（構造化ログ）から選べます。デフォルトは text です。
Timestamp Format: ログのタイムスタンプ形式を選択します。選択肢は以下の通りです。
- auto: ログフォーマッターに応じて自動判別します。textフォーマッターの場合は rfc3339、JSONフォーマッターの場合は epoch 形式を使用します。
- epoch: マイクロ秒精度のUnixエポック形式でタイムスタンプを表します。
- rfc3339: RFC3339準拠の日付時刻文字列形式。例：2024-03-26T11:52:19.777087+00:00
Time Offset: ログのタイムスタンプに適用する時刻オフセットを設定します。system（ローカルシステムのオフセット）、utc（UTC）、または +-[hh]:[mm] 形式の固定オフセット（例：-02:00、+00:00）を指定可能です。デフォルトは system です。この設定はJSONログには影響しません（JSONログはUnixエポック形式のタイムスタンプを使用するため）。
Payload Encode: ログ内のペイロードデータのエンコード方法を選択します。選択肢は以下の通りです。
- text: テキストエンコード。テキストベースのプロトコルやJSONエンコードされたペイロードに推奨されます。
- hex: 16進数エンコード。カスタムバイナリプロトコルに推奨されます。
- hidden: ペイロードを ****** に置き換えます。
デフォルトは text です。

設定が完了したら Save Changes をクリックしてください。

ファイルログの設定

Logging ページで File Log タブを選択します。

ファイルログ出力の設定項目は以下の通りです。

Enable Log Output: トグルスイッチをクリックしてファイルログ出力を有効化します。
Log File Name: ログファイルのパスとファイル名を入力します。デフォルトは ${EMQX_LOG_DIR}/emqx.log で、${EMQX_LOG_DIR} はEMQXのログディレクトリを指します。
Max Log Files Number: ローテーションされるログファイルの最大数を指定します。デフォルトは 10 です。
Rotation Size: ログファイルのローテーションを行う最大サイズを設定します。値を入力し、KB、MB、GB の単位を選択します。デフォルトは 50 MB です。トグルをオフにすると値は infinity となり、サイズによるローテーションは行われません。
Log Level: 記録する最低ログレベルを選択します。選択肢は debug, info, notice, warning, error, critical, alert, emergency です。デフォルトは warning です。
Log Formatter: ログのフォーマットを選択します。text（自由形式テキスト）または json（構造化ログ）から選べます。デフォルトは text です。
Timestamp Format: ログのタイムスタンプ形式を選択します。選択肢は以下の通りです。
- auto: ログフォーマッターに応じて自動判別します。textフォーマッターの場合は rfc3339、JSONフォーマッターの場合は epoch 形式を使用します。
- epoch: マイクロ秒精度のUnixエポック形式でタイムスタンプを表します。
- rfc3339: RFC3339準拠の日付時刻文字列形式。例：2024-03-26T11:52:19.777087+00:00
Time Offset: ログのタイムスタンプに適用する時刻オフセットを設定します。system（ローカルシステムのオフセット）、utc（UTC）、または +-[hh]:[mm] 形式の固定オフセット（例：-02:00、+00:00）を指定可能です。デフォルトは system です。この設定はJSONログには影響しません（JSONログはUnixエポック形式のタイムスタンプを使用するため）。
Payload Encode: ログ内のペイロードデータのエンコード方法を選択します。選択肢は以下の通りです。
- text: テキストエンコード。テキストベースのプロトコルやJSONエンコードされたペイロードに推奨されます。
- hex: 16進数エンコード。カスタムバイナリプロトコルに推奨されます。
- hidden: ペイロードを ****** に置き換えます。
デフォルトは text です。

設定が完了したら Save Changes をクリックしてください。

ファイルログが有効化されている場合（log.to = file または両方）、ログディレクトリには以下のファイルが生成されます。

emqx.log.N: emqx.log を接頭辞としたログファイルで、EMQXのすべてのログメッセージを含みます。例：emqx.log.1、emqx.log.2 など。
emqx.log.sizとemqx.log.idx`: ログローテーション情報を記録するシステムファイルです。手動で変更しないでください。

設定ファイルによるログ設定

設定ファイルを使ってEMQXのログ設定を行うことも可能です。例えば、警告レベルのログをファイルに出力したい場合やコンソールに出力したい場合は、base.hocon の log セクションの設定項目を以下のように変更します。設定はノード再起動後に反映されます。設定ファイルによるログ設定の詳細は Configuration - Logs を参照してください。

bash

log {
  file {
    default {
      enable = true
      formatter = text
      level = warning
      path = "/Users/emqx/Downloads/emqx-560/log/emqx.log"
      rotation_count = 10
      rotation_size = 50MB
      time_offset = system
      timestamp_format = auto
  }
  console {
    formatter = json
    level = debug
    time_offset = system
    timestamp_format = auto
  }
}

ログフォーマット

ログメッセージのフォーマット（各フィールドはスペースで区切られます）は以下の通りです。

**timestamp level tag clientid msg peername username ...**

各フィールドの説明は以下の通りです。

timestamp: ログエントリ作成時刻を示すRFC-3339形式のタイムスタンプ。
level: ログの重大度レベル。角括弧で囲まれた形式 [level] で、info、warning、error などの標準ログレベルが入ります。
tag: ログの分類用に使われる全大文字の単語。検索や分析を容易にするためのもの。例：MQTT、AUTHN、AUTHZ。
clientid: 特定のクライアントに関するログの場合に含まれ、そのクライアントを識別します。
msg: ログメッセージの内容。検索性と可読性向上のため、多くのメッセージは snake_case 形式を採用しています（例：mqtt_packet_received）。ただしすべてのメッセージがこの形式とは限りません。
peername: クライアントの送信元IPアドレスとポート番号（IP:port形式）。接続元を示します。
username: クライアントに指定された非空のユーザー名がある場合に含まれます。関係するクライアントのユーザー名を示します。
...: msgフィールドの後に任意の追加フィールドが続くことがあります。必要に応じて詳細情報を提供します。

ログメッセージ例

bash

2024-03-20T11:08:39.568980+01:00 [warning] tag: AUTHZ, clientid: client1, msg: cannot_publish_to_topic_due_to_not_authorized, peername: 127.0.0.1:47860, username: user1, topic: republish-event/1, reason: not_authorized

ログスロットリング

ログスロットリングは、指定した時間ウィンドウ内で繰り返し発生する同一イベントのログ出力を制限し、ログの洪水を防ぐ機能です。最初のイベントのみをログに記録し、その後の同一イベントは抑制することで、観測性を損なわずにログ管理の効率化を図ります。

ダッシュボードの Management -> Logging から Throttling タブを選択し、スロットリングの時間ウィンドウを設定できます。デフォルトは1分、最小設定値は1秒です。

設定ファイルで直接時間ウィンドウを設定する例は以下の通りです。

log {
  throttling {
    time_window = "5m"
  }
}

ログスロットリングはデフォルトで有効であり、認証失敗やメッセージキューのオーバーフローなど特定のログイベントに適用されます。ただし、console または file のログレベルが debug に設定されている場合は、詳細なログを確実に出力するためスロットリングは無効化されます。

スロットリングが適用されるログイベントは以下の通りです。

"authentication_failure"
"authorization_permission_denied"
"cannot_publish_to_topic_due_to_not_authorized"
"cannot_publish_to_topic_due_to_quota_exceeded"
"connection_rejected_due_to_license_limit_reached"
"data_bridge_buffer_overflow"
"dropped_msg_due_to_mqueue_is_full"
"dropped_qos0_msg"
"external_broker_crashed"
"failed_to_fetch_crl"
"failed_to_retain_message"
"handle_resource_metrics_failed"
"retain_failed_for_payload_size_exceeded_limit"
"retain_failed_for_rate_exceeded_limit"
"retained_delete_failed_for_rate_exceeded_limit"
"socket_receive_paused_by_rate_limit"
"transformation_failed"
"unrecoverable_resource_error"
"validation_failed"

補足

スロットリング対象イベントのリストは更新される可能性があります。

時間ウィンドウ内でイベントがスロットリングされた場合、各イベントタイプごとに抑制された件数をまとめた警告メッセージがログに記録されます。例えば、1つのウィンドウ内で5回の認可拒否イベントが発生した場合、以下のようにログが出力されます。

2024-03-13T15:45:11.707574+02:00 [warning] clientid: test, msg: authorization_permission_denied, peername: 127.0.0.1:54870, username: test, topic: t/#, action: SUBSCRIBE(Q0), source: file
2024-03-13T15:45:53.634909+02:00 [warning] msg: log_events_throttled_during_last_period, period: 1 minutes, 0 seconds, dropped: #{authorization_permission_denied => 4}

最初の "authorization_permission_denied" イベントは完全にログに記録され、次の4件は抑制されますが、抑制件数は "log_events_throttled_during_last_period" 統計に記録されます。

本番環境でのログ集中管理

本番環境では、各EMQXノードのログをEMQXクラスター外の中央システムに送信して集中管理することを推奨します。ブローカーのホストにのみログを保持すると、ノードやストレージの障害時にログが利用できなくなる可能性があります。集中管理により、CoreノードとReplicantノード間のイベント相関や、メトリクスや組み込みアラームに現れない条件のアラートも可能になります。

収集方法の選択

以下のいずれかの収集パターンを利用してください。

Kubernetesなどのコンテナ化環境では、JSONログをコンソールに出力し、プラットフォームのログエージェントでコンテナの出力を収集する。
ファイルログの場合は、emqx.log.N ファイルを収集し、ローテーションを処理しつつ重複記録を防ぎ、構造化フィールドを保持するログエージェントを使用する。
OpenTelemetryログハンドラーを使い、ログをOpenTelemetry Collectorおよび対応バックエンドにエクスポートする。

コンテキストの追加とログ保護

収集パイプラインにクラスター、ノード、ノードロール、EMQXバージョン、アベイラビリティゾーンなどのデプロイメントメタデータを追加してください。

集中管理されたログは運用データとして保護してください。ログフィールドにはクライアントID、ユーザー名、トピック、ピアアドレス、エラー詳細などが含まれます。

収集パイプラインの監視

コレクターおよびトランスポートのヘルスメトリクスや、アプリケーションログ量に依存しない明示的なハートビートを使って収集経路を監視します。以下の条件でアラートを設定してください。

コレクターまたはトランスポートが正常でない場合
コレクターまたはトランスポートがレコードを拒否または破棄した場合
中央バックエンドのストレージ容量が逼迫している場合

単に到達可能なEMQXノードがログを出力していないだけでアラートを発するのは避けてください。アイドル状態や正常なノードは、設定された重大度で報告すべきログが存在しないことがあります。

ログアラートポリシーの定義

安定した構造化フィールド（level や msg など）に基づいてログベースのアラートを選択的に作成してください。

Warningイベント: これらは早期警告信号として有用ですが、クライアントの正常な動作によって引き起こされる場合もあります。個別のイベントで対応が不要な場合は、レートや通常のベースラインからの逸脱を基にアラートを設定してください。
ErrorまたはCriticalイベント: レプリケーションの喪失、設定同期、リスナー起動、永続ストレージ関連の問題などは通常即時アラートが必要です。

Mriaレプリケーション信号を含む推奨されるメトリクスおよびログベースのアラートセットについては、Production Monitoring Best Practices を参照してください。

ロードバランサーの設定

パフォーマンスとチューニング

ネットワークと TLS

認証

パスワード認証

認可

シングルサインオン (SSO)

監視

アクセスコントロール

統合

管理

Prometheus との統合

OpenTelemetry との統合

エンドツーエンドトレース

プラグインカタログ

ログ

ログレベル

ダッシュボードによるログ設定

コンソールログの設定

ファイルログの設定

設定ファイルによるログ設定

ログフォーマット

ログメッセージ例

ログスロットリング

本番環境でのログ集中管理

収集方法の選択

コンテキストの追加とログ保護

収集パイプラインの監視

ログアラートポリシーの定義

パスワード認証

エンドツーエンドトレース

ログ ​

ログレベル ​

ダッシュボードによるログ設定 ​

コンソールログの設定 ​

ファイルログの設定 ​

設定ファイルによるログ設定 ​

ログフォーマット ​

ログメッセージ例 ​

ログスロットリング ​

本番環境でのログ集中管理 ​

収集方法の選択 ​

コンテキストの追加とログ保護 ​

収集パイプラインの監視 ​

ログアラートポリシーの定義 ​

ログ

ログレベル

ダッシュボードによるログ設定

コンソールログの設定

ファイルログの設定

設定ファイルによるログ設定

ログフォーマット

ログメッセージ例

ログスロットリング

本番環境でのログ集中管理

収集方法の選択

コンテキストの追加とログ保護

収集パイプラインの監視

ログアラートポリシーの定義