この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/semconv/rpc/dubbo/

翻訳元: open-telemetry/semantic-conventions v1.44.0（コミット e10a930）

Apache Dubboに関するセマンティック規約

ステータス: Release Candidate（特に断りがない限り）

Apache Dubboに関するセマンティック規約は、RPCセマンティック規約を拡張・上書きします。

Spans

Client

Status:

このスパンは、送信されるリモートプロシージャコール（RPC）を表します。

rpc.system.name は "dubbo" に設定しなければならず（MUST）、スパン作成時点で提供されるべきです（SHOULD）。

Span name: 名前の節を参照してください。

Span kind は CLIENT でなければなりません（MUST）。

Span status スパンステータスの記録方法の詳細については、エラーの記録を参照してください。どの値がエラーに分類されるかの詳細は rpc.response.status_code 属性も参照してください。

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`rpc.method`	`Required`	string	RPCインターフェースの観点から見た、完全修飾されたメソッドの論理名。[1]	`com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER`
`rpc.response.status_code`	`Required`	string	サーバーが返した、またはクライアントが生成した、Dubboレスポンスステータスコードの文字列表現。[2]	`OK`; `DEADLINE_EXCEEDED`; `SERVER_ERROR`
`error.type`	`Conditionally Required` 操作が失敗した場合に限る。	string	操作が終了したエラーのクラスを記述します。[3]	`DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602`
`rpc.method_original`	`Conditionally Required` `rpc.method` と異なる場合に限る。	string	クライアントが使用した元のメソッド名。	`com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod`
`server.address`	`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`	`Conditionally Required` [5]	int	サーバーのポート番号。[6]	`20880`; `50051`
`network.peer.address`	`Recommended`	string	ネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。[7]	`10.1.2.80`; `/tmp/my.sock`
`network.peer.port`	`Recommended` `network.peer.address` が設定されている場合。	int	ネットワーク接続のピアポート番号。	`65123`
`rpc.request.metadata.<key>`	`Opt-In`	string[]	RPCリクエストのメタデータ。`<key>` は正規化されたRPCメタデータキー（小文字）で、値はそのメタデータの値。[8]	`["1.2.3.4", "1.2.3.5"]`
`rpc.response.metadata.<key>`	`Opt-In`	string[]	RPCレスポンスのメタデータ。`<key>` は正規化された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プロトコルステータスコード
Dubbo3 Tripleプロトコル: Tripleプロトコルエラーコード

[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.<key>: 計装は、どのメタデータの値を取得するかを明示的に設定できるようにすべきです（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.<key>: 計装は、どのメタデータの値を取得するかを明示的に設定できるようにすべきです（SHOULD）。すべてのレスポンスメタデータの値を含めることはセキュリティ上のリスクとなり得ます。明示的な設定によって機密情報の漏洩を避けやすくなります。

例えば、値が ["attribute_value"] であるプロパティ my-custom-key は、値 ["attribute_value"] を持つ rpc.response.metadata.my-custom-key 属性として記録されるべきです（SHOULD）。

次の属性は、サンプリングの判断を行う上で重要になる場合があり、（何であれ提供する場合には）スパン作成時点で提供されるべきです（SHOULD）。

error.type には、次の既知の値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、そうでない場合は独自の値を使用してもかまいません（MAY）。

Value	Description	Stability
`_OTHER`	計装が独自の値を定義していない場合に使うフォールバックのエラー値。

Server

Status:

このスパンは、受信するリモートプロシージャコール（RPC）を表します。

rpc.system.name は "dubbo" に設定しなければならず（MUST）、スパン作成時点で提供されるべきです（SHOULD）。

Span name: 名前の節を参照してください。

Span kind は SERVER でなければなりません（MUST）。

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`rpc.response.status_code`	`Required`	string	サーバーが返した、Dubboレスポンスステータスコードの文字列表現。[1]	`OK`; `SERVER_ERROR`; `SERVER_THREADPOOL_EXHAUSTED_ERROR`
`error.type`	`Conditionally Required` 操作が失敗した場合に限る。	string	操作が終了したエラーのクラスを記述します。[2]	`DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602`
`rpc.method`	`Conditionally Required` 利用可能な場合。	string	RPCインターフェースの観点から見た、完全修飾されたメソッドの論理名。[3]	`com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER`
`rpc.method_original`	`Conditionally Required` `rpc.method` と異なる場合に限る。	string	クライアントが使用した元のメソッド名。	`com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod`
`server.address`	`Conditionally Required` 利用可能な場合。	string	リクエストの送信先であるRPCサーバーインスタンスのグループを識別する文字列。[4]	`example.com`; `10.1.2.80`; `/tmp/my.sock`
`server.port`	`Conditionally Required` [5]	int	サーバーのポート番号。[6]	`80`; `8080`; `443`
`network.peer.address`	`Recommended`	string	ネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。[7]	`10.1.2.80`; `/tmp/my.sock`
`network.peer.port`	`Recommended` `network.peer.address` が設定されている場合。	int	ネットワーク接続のピアポート番号。	`65123`
`rpc.request.metadata.<key>`	`Opt-In`	string[]	RPCリクエストのメタデータ。`<key>` は正規化されたRPCメタデータキー（小文字）で、値はそのメタデータの値。[8]	`["1.2.3.4", "1.2.3.5"]`
`rpc.response.metadata.<key>`	`Opt-In`	string[]	RPCレスポンスのメタデータ。`<key>` は正規化された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プロトコルステータスコード
Dubbo3 Tripleプロトコル: Tripleプロトコルエラーコード

[2] error.type: ステータスコードが返される前にRPCがエラーで失敗した場合、error.type は例外の型（該当する場合は完全修飾クラス名）またはコンポーネント固有の低カーディナリティなエラー識別子に設定すべきです（SHOULD）。

リクエストが正常に完了した場合、計装は error.type を設定すべきではありません（SHOULD NOT）。

[3] rpc.method: メソッド名は、エッジケースやエラーケースにおいて無制限のカーディナリティを持つことがあります（MAY）。

RPC計装が有効なRPCメソッドを _OTHER に変換してしまう可能性がある場合、既知のRPCメソッドの一覧を設定する方法を提供すべきです（SHOULD）。

[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）。

Value	Description	Stability
`_OTHER`	計装が独自の値を定義していない場合に使うフォールバックのエラー値。

Metrics

Dubboの計装は、RPCメトリクスに関するセマンティック規約の全般的な規約に従ってメトリクスを収集すべきです（SHOULD）。

rpc.system.name は "dubbo" に設定しなければなりません（MUST）。