# エンドツーエンドトレーシングスパンの詳細 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メッセージフローのトレースの冗長性を減らせます。