エンドツーエンドトレーシングスパンの詳細

EMQXはOpenTelemetry標準に基づくエンドツーエンドトレーシング機能を提供しています。これにより、EMQXクラスター内でのMQTTメッセージおよびクライアントのアクティビティの全ライフサイクルを監視できます。本ページでは、EMQXが生成するスパンについて説明し、それらがブローカーの内部動作のどの部分を示しているかを解説します。

クライアントライフサイクルスパン

これらのスパンはMQTTクライアントの主要なライフサイクルイベントをトレースします。

• client.connect：クライアント接続プロセスをトレースするルートスパンです。クライアントがブローカーへの接続を開始した時点で開始し、接続が確立されるか拒否されるまで続きます。

• client.disconnect：クライアントの切断プロセスをトレースします。クライアントがDISCONNECTパケットを送信した時、またはネットワークエラーやキープアライブタイムアウトなどの理由で接続が切断された時に開始します。

• client.subscribe：クライアントのサブスクライブ要求をトレースします。ブローカーがSUBSCRIBEパケットを受信し、サブスクリプションを処理し、SUBACKパケットを送信するまでの全過程をカバーします。

• client.unsubscribe：クライアントのサブスクリプション解除要求をトレースします。UNSUBSCRIBEパケットの受信からUNSUBACKパケットの送信までの過程をカバーします。

認証および認可スパン

これらのスパンはEMQXがどのように認証および認可チェックを行っているかを示します。

• client.authn：クライアントの認証プロセスをトレースします。このスパンはclient.connectスパンの子スパンです。

• client.authn_backend：認証中の特定のバックエンド呼び出し（例：データベース照会、HTTPサービス呼び出し）をトレースします。client.authnの子スパンであり、認証バックエンドのパフォーマンスボトルネック特定に役立ちます。

• client.authz：クライアントの認可プロセスをトレースします。パブリッシュまたはサブスクライブ操作時に発生します。

• client.authz_backend：認可中の特定のバックエンド呼び出しをトレースします。client.authzの子スパンです。

メッセージライフサイクルスパン

これらのスパンはMQTTメッセージがブローカー内を通過する過程をトレースします。

イングレス（クライアントからブローカーへ）

• client.publish：クライアントがブローカーにメッセージをパブリッシュしたことをトレースするルートスパンです。ブローカーがPUBLISHパケットを受信した時点で開始します。

• message.route：client.publishの子スパンで、メッセージがブローカー内でルーティングされ、マッチするサブスクライバーを探す過程をトレースします。

• message.forward：メッセージをクラスター内の別ノードのサブスクライバーに配信する必要がある場合、そのノードへの転送をトレースします。message.routeの子スパンです。

• message.handle_forward：受信ノードで転送されたメッセージの処理をトレースします。

エグレス（ブローカーからクライアントへ）

• broker.publish：ブローカーがメッセージをサブスクライバーに配信する準備とパブリッシュ処理をトレースします。message.routeまたはmessage.handle_forwardの子スパンです。

QoSアック（Acknowledgement）スパン

これらのスパンはQoS 1およびQoS 2のアックフローをトレースします。

ブローカーからパブリッシャーへ

• broker.puback：ブローカーがパブリッシャーにPUBACKを送信する処理をトレースします（QoS 1）。

• broker.pubrec：ブローカーがパブリッシャーにPUBRECを送信する処理をトレースします（QoS 2）。

• broker.pubcomp：ブローカーがパブリッシャーにPUBCOMPを送信し、QoS 2フローを完了する処理をトレースします。

パブリッシャーからブローカーへ

• client.pubrel：ブローカーがパブリッシャーからPUBRELを受信する処理をトレースします（QoS 2）。

ブローカーからサブスクライバーへ

• broker.pubrel：ブローカーがサブスクライバーにPUBRELを送信する処理をトレースします（QoS 2）。

サブスクライバーからブローカーへ

• client.puback：ブローカーがサブスクライバーからPUBACKを受信する処理をトレースします（QoS 1）。

• client.pubrec：ブローカーがサブスクライバーからPUBRECを受信する処理をトレースします（QoS 2）。

• client.pubcomp：ブローカーがサブスクライバーからPUBCOMPを受信し、QoS 2フローを完了する処理をトレースします。

ルールエンジンスパン

これらのスパンはEMQXルールエンジン内の実行をトレースします。

• broker.rule_engine.apply：メッセージがルールに対して評価される過程をトレースします。message.routeの子スパンです。

• broker.rule_engine.action：マッチしたルールによってトリガーされた特定のアクションの実行をトレースします。broker.rule_engine.applyの子スパンです。

ブローカー内部スパン

これらのスパンはクライアントから直接開始されないブローカー内部の操作をトレースします。

• broker.disconnect：ブローカーがクライアントを積極的に切断した場合（例：管理操作による）をトレースします。

• broker.subscribe：ブローカー自身が開始した内部サブスクリプション処理（例：管理操作による）をトレースします。

• broker.unsubscribe：内部のサブスクリプション解除処理をトレースします。

トレースのサンプリングとフィルタリング

EMQXのOpenTelemetry統合には柔軟なサンプラーが含まれており、どのトレースを生成するかを制御できます。これによりトレースデータの量を管理し、特定のクライアント、トピック、イベントタイプに注力できます。トレースのサンプリング決定は以下の階層に基づいて行われます。

1. トレースコンテキストのソース：EMQXが受信したMQTTパケットからトレースコンテキストを抽出するかどうかを制御します。これはfollow_traceparentというブールスイッチで制御されます。

   • true（デフォルト）の場合、EMQXは受信リクエスト（例：MQTTパケットのtraceparentユーザープロパティ）からトレースコンテキストを抽出しようとします。これにより、上流のインストルメンテーションされたアプリケーションから始まるトレースをリンクできます。
   • falseの場合、EMQXは受信したトレースコンテキストを無視し、常に新しいトレースを開始します。

2. リモートサンプリングの決定：follow_traceparentがtrueで、受信リクエストにすでに「サンプリング済み」とマークされたトレースコンテキストが含まれている場合、EMQXはこの上流の決定を尊重し、他のルールで上書きされない限りトレースをサンプリングします。

3. ホワイトリストルール：リモート親によってまだサンプリングされていない場合、特定のクライアントやトピックに対して強制的にサンプリングするルールを定義できます。これは関心のあるアクティビティを確実にトレースする最も直接的な方法です。

   • ClientIDホワイトリスト：ルートレベルのすべてのアクティビティ（接続、サブスクライブ、パブリッシュなど）に対してサンプリングを強制します。

   • トピックホワイトリスト：マッチするトピックにパブリッシュされたメッセージに対してサンプリングを強制します。

     注意: このルールはトレースの開始時（例：client.publishスパン）に適用されます。サブスクライバーへのメッセージ配信を担当するbroker.publishスパンには適用されません。

4. 比率ベースのサンプリング：ホワイトリストルールにマッチしない場合、sample_ratio設定で制御される比率ベースのサンプリングにフォールバックします。

   この比率は0.0から1.0の範囲で設定でき、キャプチャするトレースの割合を制御します。1.0は100%のトレースをキャプチャし、0.0はホワイトリストルールにマッチしない限りトレースをキャプチャしません。

5. イベントタイプスイッチ：比率ベースのサンプラーでトレースが選択されても、関連するイベントタイプスイッチが有効でなければトレースは生成されません。これらのスイッチはスパンのカテゴリごとのグローバルなオン／オフを制御します。利用可能なスイッチは以下の通りです。

   • client_connect_disconnect：クライアントの接続および切断イベントのトレースを有効または無効にするブールスイッチ。
   • client_subscribe_unsubscribe：クライアントのサブスクライブおよびサブスクリプション解除イベントのトレースを有効または無効にするブールスイッチ。
   • client_messaging：クライアントのメッセージパブリッシュのトレースを有効または無効にするブールスイッチ。
   • trace_rule_engine：ルールエンジンのトレースを有効または無効にするブールスイッチ。

6. メッセージトレースレベル：QoSアック（例：PUBACK、PUBREC）に関連するスパンの生成は、msg_trace_levelスイッチでQoSレベルに基づいて制御できます。

   • msg_trace_level：この設定は特定のQoSレベル（0、1、2）に設定でき、元のメッセージのQoSに基づいてどのアック系スパンを生成するかを制御します。

     例えば、msg_trace_levelが1に設定されている場合、QoS 1メッセージに対してPUBACKスパンが生成されます。QoS 2メッセージの場合、この設定はPUBRECスパンを生成しますが、PUBRELやPUBCOMPスパンは生成しません。これにより、高QoSメッセージフローのトレースの冗長性を減らせます。