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：トレースデータのエクスポート先URLを1つ入力します。URLは http または https スキームを使用し、明示的なポート番号を含める必要があります。デフォルトは http://localhost:4317 です。localhost:4317 や http://localhost のような値は無効です。

   • 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：スパン属性にクラスタ識別用のプロパティ値を追加します。プロパティキーは 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 ファイルに以下の設定を追加します。

opentelemetry.exporter.endpoint は1つのURLを受け入れます。URLは http または https スキームを使用し、明示的なポート番号を含める必要があります。例：http://localhost:4317 は有効ですが、localhost:4317 や http://localhost は無効です。

設定オプションの詳細は、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メッセージの詳細なトレースを確認できます。

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

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

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

   

   さらに、メッセージやイベントがルールエンジンの実行をトリガーする場合、ルールエンジントラッキングが有効であれば、ルールおよびアクションの実行トラッキング情報も取得可能です。

   

   TIP

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

   重要なお知らせ

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

トレーススパンの理解

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

主なスパン種類の概要は以下の通りです：

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

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

トレーススパンの過負荷管理

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

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

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

注意

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

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

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