OpenTelemetryベースのエンドツーエンドMQTTトレーシング

現代の分散システムにおいて、リクエストの流れを追跡しパフォーマンスを分析することは、信頼性と可観測性を確保するために不可欠です。エンドツーエンドトレーシングは、リクエストの開始から終了までの全経路をキャプチャすることを目的とした概念であり、システムの挙動やパフォーマンスに関する深い洞察を得ることができます。

EMQXはバージョン5.8.3より、MQTTプロトコルに特化したOpenTelemetryベースのエンドツーエンドトレーシング機能を統合しています。この機能により、特にマルチノードクラスター環境において、メッセージのパブリッシュ、ルーティング、配信の流れを明確にトレースできます。これにより、システムパフォーマンスの最適化だけでなく、迅速な障害箇所の特定やシステムの信頼性向上にも役立ちます。

本ページでは、MQTTメッセージのフローを包括的に可視化するために、EMQXでエンドツーエンドトレーシング機能を有効化する手順を詳しく解説します。

OpenTelemetryコレクターのセットアップ

設定の詳細については、OpenTelemetryコレクターのセットアップを参照してください。

EMQXでのエンドツーエンドトレーシングの有効化

TIP

エンドツーエンドトレーシングはシステムパフォーマンスに影響を与える可能性があるため、必要な場合のみ有効にしてください。

このセクションでは、EMQXでOpenTelemetryベースのエンドツーエンドトレーシングを有効化する方法を案内し、マルチノード環境でのMQTT分散トレーシング機能を紹介します。

ダッシュボードからのエンドツーエンドトレーシング設定

1. ダッシュボードの左メニューから Management -> Monitoring をクリックします。

2. Monitoringページの Integration タブを選択します。

3. 以下の設定を行います：

   • Monitoring platform：OpenTelemetry を選択します。

   • Feature Selection：Traces を選択します。

   • Endpoint：トレースデータのエクスポート先アドレスを設定します。デフォルトは http://localhost:4317 です。

   • Headers：トレースエクスポートリクエストにカスタムHTTPヘッダーを追加します。OpenTelemetryコレクターが認証やAPIキー、トークンなどのカスタムヘッダーを必要とする場合に使用します。各ヘッダーはキーと値のペアで指定してください。

     OpenTelemetryコレクターがBasic認証を使用する場合は、authorization ヘッダーに Basic <base64エンコードされたユーザー名:パスワード> の形式で値を設定する必要があります。例：

     Key: authorization
     Value: Basic dXNlcjpwYXNzd29yZA==

     このオプションにより、HTTPベースの認証を強制するコレクターとの互換性が向上します。

   • Enable TLS：必要に応じてTLS暗号化を有効にします。通常は本番環境のセキュリティ要件に応じて設定します。

   • Trace Mode：End-to-End を選択し、エンドツーエンドトレーシング機能を有効にします。

   • Cluster Identifier：span属性にクラスタ識別用のプロパティ値を追加します。プロパティキーは cluster.id です。通常はシンプルで識別しやすい名前やクラスター名を設定し、EMQXクラスター間の区別に利用します。デフォルトは emqxcl です。

   • Traces Export Interval：トレースデータのエクスポート間隔を秒単位で設定します。デフォルトは 5 秒です。

   • Max Queue Size：トレースデータキューの最大サイズを設定します。デフォルトは 2048 エントリです。

4. 必要に応じて Trace Advanced Configuration をクリックし、詳細設定を行います。

   • Trace Configuration：クライアント接続やメッセージ送受信、ルールエンジン実行など、特定イベントのトレース有無を設定できます。
     • Follow Traceparent：traceparent を追従するかどうかを設定します。true に設定すると、EMQXはクライアントから送信された User-Property 内の traceparent 識別子を取得し、エンドツーエンドトレーシングに紐付けます。false の場合は新しいトレースを生成します。デフォルトは true です。
   • Client ID White List：トレース対象とするクライアント接続やメッセージを制限するホワイトリストを設定します。不要なトレースを避け、システムリソースの消費を抑制できます。
   • Topic White List：トピックのホワイトリストを設定し、マッチするトピックのみをトレース対象とします。クライアントホワイトリストと同様にトレース範囲を制御します。

   設定保存後、Confirm をクリックしてウィンドウを閉じます。

5. Save Changes をクリックして設定を保存します。

設定ファイルによるエンドツーエンドトレーシング設定

EMQXの cluster.hocon ファイルに以下の設定を追加します（EMQXがローカルで動作している前提）。

設定オプションの詳細は、EMQXダッシュボード監視統合のOpenTelemetryセクションを参照してください。

opentelemetry {
  exporter {
    endpoint = "http://localhost:4317"
    headers {
      authorization = ""Basic dXNlcjpwYXNzd29yZA=="
    }
  }
  traces {
    enable = true
    # エンドツーエンドトレーシングモード
    trace_mode = e2e
    # エンドツーエンドトレーシングオプション
    e2e_tracing_options {
      ## クライアント接続/切断イベントのトレース
      client_connect_disconnect = true
      ## クライアントメッセージングイベントのトレース
      client_messaging = true
      ## クライアントサブスクライブ/アンサブスクライブイベントのトレース
      client_subscribe_unsubscribe = true
      ## クライアントIDホワイトリストの最大長
      clientid_match_rules_max = 30
      ## トピックフィルターホワイトリストの最大長
      topic_match_rules_max = 30
      ## クラスター識別子
      cluster_identifier = emqxcl
      ## メッセージトレースレベル（QoS）
      msg_trace_level = 2
      ## ホワイトリスト外イベントのサンプリング率
      ## 注意：トレース有効時のみ適用
      sample_ratio = "100%"
      ## traceparentの追従
      ## クライアントから渡される`traceparent`をエンドツーエンドトレーシングで追従するか
      follow_traceparent
    }
  }
  max_queue_size = 50000
  scheduled_delay = 1000
}

EMQXでのエンドツーエンドトレーシングのデモ

1. EMQXノードを起動します。例として、emqx@172.19.0.2 と emqx@172.19.0.3 の2ノードクラスターを起動し、分散トレーシング機能をデモします。

2. MQTTX CLIをクライアントとして使用し、異なるノードで同じトピックをサブスクライブします。

   • emqx@172.19.0.2 ノードでサブスクライブ：

     mqttx sub -t t/1 -h 172.19.0.2 -p 1883

   • emqx@172.19.0.3 ノードでサブスクライブ：

     mqttx sub -t t/1 -h 172.19.0.3 -p 1883

3. 約5秒後（EMQXのトレースデータエクスポートのデフォルト間隔）、http://localhost:16686 のJaeger WEB UIにアクセスし、トレースデータを確認します。

   emqx サービスを選択し、Find Traces をクリックします。emqx サービスがすぐに表示されない場合は、少し待ってページを更新してください。クライアントの接続およびサブスクライブイベントのトレースが表示されます：

   

4. メッセージをパブリッシュします：

   mqttx pub -t t/1 -h 172.19.0.2 -p 1883

5. 少し待つと、Jaeger WEB UIでMQTTメッセージの詳細なトレースが確認できます。

   トレースをクリックすると、詳細なspan情報とトレースタイムラインが表示されます。サブスクライバー数、クロスノードのメッセージルーティング、QoSレベル、msg_trace_level の設定により、MQTTメッセージトレースに含まれるspan数は異なります。

   以下は、2クライアントがQoS 2でサブスクライブし、パブリッシャーがQoS 2メッセージを送信、msg_trace_level が2に設定されている場合のトレースタイムラインとspan情報の例です。

   特に、クライアント mqttx_9137a6bb がパブリッシャーとは異なるEMQXノードに接続されているため、クロスノード伝送を表す2つの追加span（message.forward と message.handle_forward）が現れています。

   

   また、メッセージやイベントがルールエンジンの実行をトリガーした場合、ルールエンジンのトレースオプションが有効であれば、ルールおよびアクションの実行トレース情報も取得可能です。

   

   TIP

   ルールエンジン実行を伴うエンドツーエンドトレーシング機能は、EMQXバージョン5.9.0以降でサポートされています。

   重要なお知らせ

   この機能は慎重に有効化してください。メッセージやイベントが複数のルールやアクションをトリガーすると、1つのトレースで大量のspanが生成され、システム負荷が増大します。 メッセージ量やルール・アクション数に基づき、適切なサンプリング率を見積もってください。

トレースspanの理解

EMQXはエンドツーエンドトレーシング中にさまざまな種類のspanを生成し、ブローカー内部の詳細な動作を可視化します。これらのspanはクライアントライフサイクル、メッセージライフサイクル、認証・認可、ルールエンジン、ブローカー内部処理など多岐にわたります。

主なspanタイプの概要は以下の通りです：

• クライアントライフサイクルspan：クライアントの接続、切断、サブスクライブ、アンサブスクライブなど主要なライフサイクルイベントをトレースします。
• 認証・認可span：クライアントに対して実施される認証および認可処理の可視化を提供します。
• メッセージライフサイクルspan：MQTTメッセージの受信、ルーティング、転送、QoSレベルごとのアックフローなど、メッセージの完全な経路をトレースします。
• ルールエンジンスパン：ルールエンジンの処理および実行をトレースします。
• ブローカー内部span：クライアントの強制切断や内部サブスクライブなど、ブローカー内部の操作をトレースします。

各spanの詳細については、エンドツーエンドトレーシングspanの詳細を参照してください。

トレースspanの過負荷管理

EMQXはトレースspanを蓄積し、一定間隔でバッチエクスポートします。エクスポート間隔は opentelemetry.trace.scheduled_delay パラメータで制御され、デフォルトは5秒です。バッチトレースspanプロセッサには過負荷保護があり、蓄積可能なspan数の上限（デフォルト2048span）を超えると新しいspanは破棄されます。以下の設定で上限を調整可能です：

opentelemetry {
  traces {
    max_queue_size = 50000
    scheduled_delay = 1000
  }
}

max_queue_size の上限に達すると、現在のキューがエクスポートされるまで新規トレースspanは破棄されます。

補足

トレース対象のメッセージが多数のサブスクライバーに配信される場合や、メッセージ量が多くサンプリング率が高い場合、過負荷保護により多くのspanが破棄され、エクスポートされるspanはごく一部になる可能性があります。

エンドツーエンドトレーシングモードでは、メッセージ量やサンプリング率に応じて max_queue_size を増やし、scheduled_delay を短縮してspanのエクスポート頻度を上げることを検討してください。これにより過負荷保護によるspanの損失を防げます。

ただし、エクスポート頻度の増加やキューサイズの拡大はシステムリソース消費を増加させるため、メッセージTPSや利用可能なシステムリソースを十分に見積もった上で適切な設定を行ってください。