エンドツーエンドトレーシングスパンの詳細
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統合には柔軟なサンプラーが含まれており、どのトレースを生成するかを制御できます。これによりトレースデータの量を管理し、特定のクライアント、トピック、イベントタイプにフォーカスできます。トレースをサンプリングするかどうかの判断は以下の階層に基づいて行われます。
トレースコンテキストのソース: EMQXが受信したMQTTパケットからトレースコンテキストを抽出するかどうかを決定します。これは
follow_traceparentというブールスイッチで制御されます。true（デフォルト）の場合、EMQXは受信リクエスト（例：MQTTパケットのtraceparentユーザープロパティ）からトレースコンテキストを抽出しようとします。これにより上流の計測済みアプリケーションから始まるトレースを連結できます。falseの場合、EMQXは受信したトレースコンテキストを無視し、常に新しいトレースを開始します。
リモートサンプリングの判断:
follow_traceparentがtrueで、受信リクエストに既に「サンプリング済み」とマークされたトレースコンテキストが含まれている場合、EMQXはこの上流の判断を尊重し、他のルールで上書きされない限りトレースをサンプリングします。ホワイトリストルール: リモート親によるサンプリングがされていない場合、特定のクライアントやトピックに対して強制的にサンプリングを行うルールを定義できます。これは関心のあるアクティビティを確実にトレースする最も直接的な方法です。
ClientIDホワイトリスト: ルートレベルのすべてのアクティビティ（接続、サブスクライブ、パブリッシュなど）に対してサンプリングを強制します。
トピックホワイトリスト: マッチするトピックにパブリッシュされたメッセージに対してサンプリングを強制します。
注意: このルールはトレースの開始時（例：
client.publishスパン）に適用されます。サブスクライバーへのメッセージ配信を担当するbroker.publishスパンには適用されません。
比率ベースのサンプリング: ホワイトリストルールにマッチしない場合、
sample_ratio設定で制御される比率ベースのサンプリングにフォールバックします。この比率は
0.0から1.0の範囲で設定でき、トレースをキャプチャする割合を制御します。1.0は100%のトレースをキャプチャし、0.0はホワイトリストルールにマッチしない限りトレースをキャプチャしません。イベントタイプスイッチ: 比率ベースのサンプラーでトレースが選択されても、該当するイベントタイプスイッチが有効でなければトレースは生成されません。これらのスイッチはスパンのカテゴリごとのグローバルなオン/オフを制御します。利用可能なスイッチは以下の通りです。
client_connect_disconnect: クライアントの接続および切断イベントのトレースを有効または無効にするブールスイッチ。client_subscribe_unsubscribe: クライアントのサブスクライブおよびサブスクライブ解除イベントのトレースを有効または無効にするブールスイッチ。client_messaging: クライアントのメッセージパブリッシュのトレースを有効または無効にするブールスイッチ。trace_rule_engine: ルールエンジンのトレースを有効または無効にするブールスイッチ。
メッセージトレースレベル: 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メッセージフローのトレースの冗長さを軽減できます。