> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/rpc/dubbo/ # Apache Dubboに関するセマンティック規約 **ステータス**: [Release Candidate][DocumentStatus]（特に断りがない限り） [Apache Dubbo](https://dubbo.apache.org/)に関するセマンティック規約は、[RPCセマンティック規約](/works/otel-specs-ja/semconv/rpc/)を拡張・上書きします。 ## Spans ### Client **Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) このスパンは、送信されるリモートプロシージャコール（RPC）を表します。 `rpc.system.name` は `"dubbo"` に設定しなければならず（MUST）、**スパン作成時点**で提供されるべきです（SHOULD）。 **Span name:** [名前](/works/otel-specs-ja/semconv/rpc/rpc-spans/#名前)の節を参照してください。 **Span kind** は `CLIENT` でなければなりません（MUST）。 **Span status** スパンステータスの記録方法の詳細については、[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)を参照してください。どの値がエラーに分類されるかの詳細は `rpc.response.status_code` 属性も参照してください。 **Attributes:** | Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`rpc.method`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | RPCインターフェースの観点から見た、完全修飾されたメソッドの論理名。[1] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | サーバーが返した、またはクライアントが生成した、Dubboレスポンスステータスコードの文字列表現。[2] | `OK`; `DEADLINE_EXCEEDED`; `SERVER_ERROR` | | [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` 操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[3] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | | [`rpc.method_original`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` `rpc.method` と異なる場合に限る。 | string | クライアントが使用した元のメソッド名。 | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | | [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` 利用可能な場合。 | string | リクエストの送信先であるRPCサーバーインスタンスのグループを識別する文字列。[4] | `192.168.1.100`; `api.example.com`; `zookeeper://127.0.0.1:2181/com.example.HelloService:1.0.0:testGroup` | | [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | サーバーのポート番号。[6] | `20880`; `50051` | | [`network.peer.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | ネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。[7] | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` `network.peer.address` が設定されている場合。 | int | ネットワーク接続のピアポート番号。 | `65123` | | [`rpc.request.metadata.`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPCリクエストのメタデータ。`` は正規化されたRPCメタデータキー（小文字）で、値はそのメタデータの値。[8] | `["1.2.3.4", "1.2.3.5"]` | | [`rpc.response.metadata.`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPCレスポンスのメタデータ。`` は正規化されたRPCメタデータキー（小文字）で、値はそのメタデータの値。[9] | `["attribute_value"]` | **[1] `rpc.method`:** メソッド名は、エッジケースやエラーケースにおいて無制限のカーディナリティを持つことがあります（MAY）。 一部のRPCフレームワークやライブラリは、クライアントスタブとサーバー実装に対して、既知のメソッドの固定集合を提供します。そのようなフレームワーク向けの計装は、メソッドがフレームワークやライブラリによって認識されている場合に限り、この属性を元のメソッド名に設定しなければなりません（MUST）。 メソッドが認識されない場合、例えばサーバーがサーバー上で事前定義されていないメソッドへのリクエストを受信した場合や、計装がメソッドが事前定義されているかどうかを確実に検出できない場合、この属性は `_OTHER` に設定しなければなりません（MUST）。 RPC計装が有効なRPCメソッドを `_OTHER` に変換してしまう可能性がある場合、既知のRPCメソッドの一覧を設定する方法を提供すべきです（SHOULD）。 `rpc.method` は、実装しているメソッド・関数の名前とは異なることがあります。 `code.function.name` 属性は、サーバー側で実際に呼び出しを実行している完全修飾メソッド、またはクライアント側のRPCクライアントスタブメソッドを記録するために使用できます。 **[2] `rpc.response.status_code`:** `OK` 以外のすべてのステータスコードはエラーとみなすべきです（SHOULD）。 ステータスコードの参考資料: - Dubbo2: [Dubbo2プロトコルステータスコード](https://dubbo.apache.org/en/overview/reference/protocols/tcp/#protocol-specification) - Dubbo3 Tripleプロトコル: [Tripleプロトコルエラーコード](https://dubbo.apache.org/en/overview/reference/protocols/triple-spec/#311-request) **[3] `error.type`:** ステータスコードが返される前にRPCがエラーで失敗した場合、`error.type` は例外の型（該当する場合は完全修飾クラス名）またはコンポーネント固有の低カーディナリティなエラー識別子に設定すべきです（SHOULD）。 レスポンスのステータスコードが返され、そのステータスがエラーを示している場合、`error.type` はそのステータスコードに設定すべきです（SHOULD）。`rpc.response.status_code` のどの値がエラーとみなされるかの詳細は、システム固有の規約を確認してください。 `error.type` の値は予測可能であるべきで（SHOULD）、低カーディナリティであるべきです（SHOULD）。計装は報告するエラーの一覧を文書化すべきです（SHOULD）。 リクエストが正常に完了した場合、計装は `error.type` を設定すべきではありません（SHOULD NOT）。 **[4] `server.address`:** 計装は、Dubboクライアントの作成時に使用された設定に基づいて `server.address`（および該当する場合は `server.port`）を設定すべきで（SHOULD）、低カーディナリティを保証するために実際のネットワークレベルの接続情報をこの目的で使用すべきではありません（SHOULD NOT）。 直接接続の場合、コンシューマーが明示的なプロバイダーのターゲットURLで設定されているときは、計装はそのURLから `server.address` と `server.port` を解析すべきです（SHOULD）。 レジストリを介したサービスディスカバリーの場合、計装は `server.address` をサービスディスカバリーのターゲットに設定すべきで（SHOULD）、`server.port` は設定すべきではありません（SHOULD NOT）。サービスディスカバリーのターゲットは次のとおりです。 `{registry-protocol}://{registry-host}:{registry-port}/{logical-service-target}` `{registry-port}` の部分は、サービスディスカバリーのターゲットにおけるレジストリエンドポイントの一部であり、Dubbo RPC通信で使用されるネットワーク転送のポートではないため、`server.port` として記録すべきではありません（SHOULD NOT）。 これは、レジストリエンドポイントとロジカルサービスターゲットの間の `/` で区切られた2つの部分で構成されます。 - レジストリエンドポイント: `{registry-protocol}://{registry-host}:{registry-port}` - ロジカルサービスターゲット: `{interface}[:{version}][:{group}]`。これはコンシューマーURLから導かれ、次のように構成されます。 - `{interface}` はコンシューマーURLのサービスインターフェース名です。 - `{version}` は `version` URLパラメータが設定されている場合のその値です。 - `{group}` は `group` URLパラメータが設定されている場合のその値です。 - `{group}` のみが設定されている場合、形式は `{interface}::{group}` になります。 例: 直接接続: - ターゲットURL `dubbo://192.168.1.100:20880/com.example.DemoService` が与えられた場合、想定される属性は次のとおりです。 - `server.address`: `"192.168.1.100"` - `server.port`: `20880` - ターゲットURL `tri://api.example.com:50051/com.example.GreeterService` が与えられた場合、想定される属性は次のとおりです。 - `server.address`: `"api.example.com"` - `server.port`: `50051` - ターゲットURL `tri://api.example.com/com.example.GreeterService`（ポート未指定）が与えられた場合、想定される属性は次のとおりです。 - `server.address`: `"api.example.com"` - `server.port`: 設定なし サービスディスカバリー（レジストリ）: - コンシューマーが、`version=1.0.0` かつ `group=testGroup` の `com.example.HelloService` に対してZooKeeper経由でプロバイダーを発見する場合、想定される属性は次のとおりです。 - サービスディスカバリーのターゲット: `"zookeeper://127.0.0.1:2181/com.example.HelloService:1.0.0:testGroup"` - `server.address`: `"zookeeper://127.0.0.1:2181/com.example.HelloService:1.0.0:testGroup"` - `server.port`: 設定なし - コンシューマーが、`group=gray`（バージョンなし）の `com.example.HelloService` に対してNacos経由でプロバイダーを発見する場合、想定される属性は次のとおりです。 - サービスディスカバリーのターゲット: `"nacos://127.0.0.1:8848/com.example.HelloService::gray"` - `server.address`: `"nacos://127.0.0.1:8848/com.example.HelloService::gray"` - `server.port`: 設定なし アドレスがIPアドレスである場合、計装は逆引きDNSルックアップを行ってDNS名を得るべきではなく（SHOULD NOT）、提供されたIPアドレスを `server.address` に設定すべきです（SHOULD）。 **[5] `server.port`:** `server.address` が設定されており、かつそのポートが通信に使用されるネットワーク転送でサポートされている場合。 **[6] `server.port`:** ターゲット文字列の解析方法の詳細は `server.address` を参照してください。 **[7] `network.peer.address`:** RPCが複数のネットワーク呼び出しを含む場合（例えば再試行）、最後に接続したアドレスを使用すべきです（SHOULD）。 **[8] `rpc.request.metadata.`:** 計装は、どのメタデータの値を取得するかを明示的に設定できるようにすべきです（SHOULD）。 すべてのリクエストメタデータの値を含めることはセキュリティ上のリスクとなり得ます。明示的な設定によって機密情報の漏洩を避けやすくなります。 例えば、値が `["1.2.3.4", "1.2.3.5"]` であるプロパティ `my-custom-key` は、値 `["1.2.3.4", "1.2.3.5"]` を持つ `rpc.request.metadata.my-custom-key` 属性として記録されるべきです（SHOULD）。 **[9] `rpc.response.metadata.`:** 計装は、どのメタデータの値を取得するかを明示的に設定できるようにすべきです（SHOULD）。 すべてのレスポンスメタデータの値を含めることはセキュリティ上のリスクとなり得ます。明示的な設定によって機密情報の漏洩を避けやすくなります。 例えば、値が `["attribute_value"]` であるプロパティ `my-custom-key` は、値 `["attribute_value"]` を持つ `rpc.response.metadata.my-custom-key` 属性として記録されるべきです（SHOULD）。 次の属性は、サンプリングの判断を行う上で重要になる場合があり、（何であれ提供する場合には）**スパン作成時点**で提供されるべきです（SHOULD）。 * [`rpc.method`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) * [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) * [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) --- `error.type` には、次の既知の値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、そうでない場合は独自の値を使用してもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | 計装が独自の値を定義していない場合に使うフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ### Server **Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) このスパンは、受信するリモートプロシージャコール（RPC）を表します。 `rpc.system.name` は `"dubbo"` に設定しなければならず（MUST）、**スパン作成時点**で提供されるべきです（SHOULD）。 **Span name:** [名前](/works/otel-specs-ja/semconv/rpc/rpc-spans/#名前)の節を参照してください。 **Span kind** は `SERVER` でなければなりません（MUST）。 **Span status** スパンステータスの記録方法の詳細については、[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)を参照してください。どの値がエラーに分類されるかの詳細は `rpc.response.status_code` 属性も参照してください。 **Attributes:** | Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`rpc.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | サーバーが返した、Dubboレスポンスステータスコードの文字列表現。[1] | `OK`; `SERVER_ERROR`; `SERVER_THREADPOOL_EXHAUSTED_ERROR` | | [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` 操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` | | [`rpc.method`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` 利用可能な場合。 | string | RPCインターフェースの観点から見た、完全修飾されたメソッドの論理名。[3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` | | [`rpc.method_original`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` `rpc.method` と異なる場合に限る。 | string | クライアントが使用した元のメソッド名。 | `com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod` | | [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` 利用可能な場合。 | string | リクエストの送信先であるRPCサーバーインスタンスのグループを識別する文字列。[4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [5] | int | サーバーのポート番号。[6] | `80`; `8080`; `443` | | [`network.peer.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | ネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。[7] | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` `network.peer.address` が設定されている場合。 | int | ネットワーク接続のピアポート番号。 | `65123` | | [`rpc.request.metadata.`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPCリクエストのメタデータ。`` は正規化されたRPCメタデータキー（小文字）で、値はそのメタデータの値。[8] | `["1.2.3.4", "1.2.3.5"]` | | [`rpc.response.metadata.`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string[] | RPCレスポンスのメタデータ。`` は正規化されたRPCメタデータキー（小文字）で、値はそのメタデータの値。[9] | `["attribute_value"]` | **[1] `rpc.response.status_code`:** Dubbo2では、次のステータスコードはエラーとみなすべきです（SHOULD）。 - `SERVER_ERROR` - `SERVER_THREADPOOL_EXHAUSTED_ERROR` - `SERVER_TIMEOUT` - `SERVICE_ERROR` Dubbo3 Tripleプロトコルでは、次のステータスコードはエラーとみなすべきです（SHOULD）。 - `DATA_LOSS` - `DEADLINE_EXCEEDED` - `INTERNAL` - `UNAVAILABLE` - `UNIMPLEMENTED` - `UNKNOWN` ステータスコードの参考資料: - Dubbo2: [Dubbo2プロトコルステータスコード](https://dubbo.apache.org/en/overview/reference/protocols/tcp/#protocol-specification) - Dubbo3 Tripleプロトコル: [Tripleプロトコルエラーコード](https://dubbo.apache.org/en/overview/reference/protocols/triple-spec/#311-request) **[2] `error.type`:** ステータスコードが返される前にRPCがエラーで失敗した場合、`error.type` は例外の型（該当する場合は完全修飾クラス名）またはコンポーネント固有の低カーディナリティなエラー識別子に設定すべきです（SHOULD）。 レスポンスのステータスコードが返され、そのステータスがエラーを示している場合、`error.type` はそのステータスコードに設定すべきです（SHOULD）。`rpc.response.status_code` のどの値がエラーとみなされるかの詳細は、システム固有の規約を確認してください。 `error.type` の値は予測可能であるべきで（SHOULD）、低カーディナリティであるべきです（SHOULD）。計装は報告するエラーの一覧を文書化すべきです（SHOULD）。 リクエストが正常に完了した場合、計装は `error.type` を設定すべきではありません（SHOULD NOT）。 **[3] `rpc.method`:** メソッド名は、エッジケースやエラーケースにおいて無制限のカーディナリティを持つことがあります（MAY）。 一部のRPCフレームワークやライブラリは、クライアントスタブとサーバー実装に対して、既知のメソッドの固定集合を提供します。そのようなフレームワーク向けの計装は、メソッドがフレームワークやライブラリによって認識されている場合に限り、この属性を元のメソッド名に設定しなければなりません（MUST）。 メソッドが認識されない場合、例えばサーバーがサーバー上で事前定義されていないメソッドへのリクエストを受信した場合や、計装がメソッドが事前定義されているかどうかを確実に検出できない場合、この属性は `_OTHER` に設定しなければなりません（MUST）。 RPC計装が有効なRPCメソッドを `_OTHER` に変換してしまう可能性がある場合、既知のRPCメソッドの一覧を設定する方法を提供すべきです（SHOULD）。 `rpc.method` は、実装しているメソッド・関数の名前とは異なることがあります。 `code.function.name` 属性は、サーバー側で実際に呼び出しを実行している完全修飾メソッド、またはクライアント側のRPCクライアントスタブメソッドを記録するために使用できます。 **[4] `server.address`:** DNS名、サービスレジストリ内のエンドポイントとパス、ローカルソケット名、またはIPアドレスを含む場合があります。 個々のRPCシステムに関するセマンティック規約は、この属性への値の設定方法を文書化すべきです（SHOULD）。 アドレスがIPアドレスである場合、計装はDNS名を得るための逆引きDNSルックアップを行うべきではなく（SHOULD NOT）、`server.address` を提供されたIPアドレスに設定すべきです（SHOULD）。 **[5] `server.port`:** `server.address` が設定されており、かつそのポートが通信に使用されるネットワーク転送でサポートされている場合。 **[6] `server.port`:** クライアント側から観測され、かつ中間装置を介して通信している場合、`server.port` は利用可能であれば、プロキシなどの中間装置の背後にあるサーバーのポートを表すべきです（SHOULD）。 **[7] `network.peer.address`:** RPCが複数のネットワーク呼び出しを含む場合（例えば再試行）、最後に接続したアドレスを使用すべきです（SHOULD）。 **[8] `rpc.request.metadata.`:** 計装は、どのメタデータの値を取得するかを明示的に設定できるようにすべきです（SHOULD）。 すべてのリクエストメタデータの値を含めることはセキュリティ上のリスクとなり得ます。明示的な設定によって機密情報の漏洩を避けやすくなります。 例えば、値が `["1.2.3.4", "1.2.3.5"]` であるプロパティ `my-custom-key` は、値 `["1.2.3.4", "1.2.3.5"]` を持つ `rpc.request.metadata.my-custom-key` 属性として記録されるべきです（SHOULD）。 **[9] `rpc.response.metadata.`:** 計装は、どのメタデータの値を取得するかを明示的に設定できるようにすべきです（SHOULD）。 すべてのレスポンスメタデータの値を含めることはセキュリティ上のリスクとなり得ます。明示的な設定によって機密情報の漏洩を避けやすくなります。 例えば、値が `["attribute_value"]` であるプロパティ `my-custom-key` は、値 `["attribute_value"]` を持つ `rpc.response.metadata.my-custom-key` 属性として記録されるべきです（SHOULD）。 次の属性は、サンプリングの判断を行う上で重要になる場合があり、（何であれ提供する場合には）**スパン作成時点**で提供されるべきです（SHOULD）。 * [`rpc.method`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) * [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) * [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) --- `error.type` には、次の既知の値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、そうでない場合は独自の値を使用してもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | 計装が独自の値を定義していない場合に使うフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ## Metrics Dubboの計装は、[RPCメトリクスに関するセマンティック規約](/works/otel-specs-ja/semconv/rpc/rpc-metrics/)の全般的な規約に従ってメトリクスを収集すべきです（SHOULD）。 `rpc.system.name` は `"dubbo"` に設定しなければなりません（MUST）。 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status