この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/semconv/rpc/connect-rpc/
翻訳元: open-telemetry/semantic-conventions v1.44.0（コミット e10a930）
Connect RPCに関するセマンティック規約
ステータス: Development
Connectに関するセマンティック規約は、RPCセマンティック規約を拡張・上書きします。
Spans
Client
Status:
このスパンは、送信されるリモートプロシージャコール（RPC）を表します。
rpc.system.name は "connectrpc" に設定しなければならず（MUST）、スパン作成時点で提供されるべきです（SHOULD）。
Span name: 名前の節を参照してください。
Span kind は CLIENT でなければなりません（MUST）。
Span status: スパンステータスの記録方法の詳細については、エラーの記録を参照してください。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
server.address |  | Required | string | Connect RPCサーバーのドメイン名またはアドレス。[1] | example.com; 10.1.2.80; /tmp/my.sock |
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 |
rpc.response.status_code | | Conditionally Required 利用可能な場合。 | string | Connectレスポンスのエラーコード。[4] | OK; DEADLINE_EXCEEDED; -32602 |
server.port | | Conditionally Required 利用可能な場合。 | int | サーバーのポート番号。[5] | 80; 8080; 443 |
network.peer.address | | Recommended | string | ネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。[6] | 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メタデータキー（小文字）で、値はそのメタデータの値。[7] | ["1.2.3.4", "1.2.3.5"] |
rpc.response.metadata.<key> | | Opt-In | string[] | RPCレスポンスのメタデータ。<key> は正規化されたRPCメタデータキー（小文字）で、値はそのメタデータの値。[8] | ["attribute_value"] |
[1] server.address: ドメイン名の代わりにIPアドレスが提供された場合、計装はDNS名を得るための逆引きDNSルックアップを行うべきではなく（SHOULD NOT）、server.address を提供されたIPアドレスに設定すべきです（SHOULD）。
[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] rpc.response.status_code: OK 以外のすべてのステータスコードはエラーとみなすべきです（SHOULD）。
[5] server.port: クライアント側から観測され、かつ中間装置を介して通信している場合、server.port は利用可能であれば、プロキシなどの中間装置の背後にあるサーバーのポートを表すべきです（SHOULD）。
[6] network.peer.address: RPCが複数のネットワーク呼び出しを含む場合（例えば再試行）、最後に接続したアドレスを使用すべきです（SHOULD）。
[7] 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）。
[8] 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 は "connectrpc" に設定しなければならず（MUST）、スパン作成時点で提供されるべきです（SHOULD）。
Span name: 名前の節を参照してください。
Span kind は SERVER でなければなりません（MUST）。
Span status: スパンステータスの記録方法の詳細については、エラーの記録を参照してください。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
error.type | | Conditionally Required 操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[1] | DEADLINE_EXCEEDED; java.net.UnknownHostException; -32602 |
rpc.method | | Conditionally Required 利用可能な場合。 | string | RPCインターフェースの観点から見た、完全修飾されたメソッドの論理名。[2] | com.example.ExampleService/exampleMethod; EchoService/Echo; _OTHER |
rpc.method_original | | Conditionally Required rpc.method と異なる場合に限る。 | string | クライアントが使用した元のメソッド名。 | com.myservice.EchoService/catchAll; com.myservice.EchoService/unknownMethod; InvalidMethod |
rpc.response.status_code | | Conditionally Required 利用可能な場合。 | string | Connectレスポンスのエラーコード。[3] | OK; DEADLINE_EXCEEDED; -32602 |
server.address | | Conditionally Required 利用可能な場合。 | string | リクエストの送信先であるRPCサーバーインスタンスのグループを識別する文字列。[4] | example.com; 10.1.2.80; /tmp/my.sock |
server.port | | Conditionally Required 適用可能であり、かつ server.address が設定されている場合。 | int | サーバーのポート番号。[5] | 80; 8080; 443 |
network.peer.address | | Recommended | string | ネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。[6] | 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メタデータキー（小文字）で、値はそのメタデータの値。[7] | ["1.2.3.4", "1.2.3.5"] |
rpc.response.metadata.<key> | | Opt-In | string[] | RPCレスポンスのメタデータ。<key> は正規化されたRPCメタデータキー（小文字）で、値はそのメタデータの値。[8] | ["attribute_value"] |
[1] error.type: ステータスコードが返される前にRPCがエラーで失敗した場合、error.type は例外の型（該当する場合は完全修飾クラス名）またはコンポーネント固有の低カーディナリティなエラー識別子に設定すべきです（SHOULD）。
レスポンスのステータスコードが返され、そのステータスがエラーを示している場合、error.type はそのステータスコードに設定すべきです（SHOULD）。rpc.response.status_code のどの値がエラーとみなされるかの詳細は、システム固有の規約を確認してください。
error.type の値は予測可能であるべきで（SHOULD）、低カーディナリティであるべきです（SHOULD）。計装は報告するエラーの一覧を文書化すべきです（SHOULD）。
リクエストが正常に完了した場合、計装は error.type を設定すべきではありません（SHOULD NOT）。
[2] rpc.method: メソッド名は、エッジケースやエラーケースにおいて無制限のカーディナリティを持つことがあります（MAY）。
一部のRPCフレームワークやライブラリは、クライアントスタブとサーバー実装に対して、既知のメソッドの固定集合を提供します。そのようなフレームワーク向けの計装は、メソッドがフレームワークやライブラリによって認識されている場合に限り、この属性を元のメソッド名に設定しなければなりません（MUST）。
メソッドが認識されない場合、例えばサーバーがサーバー上で事前定義されていないメソッドへのリクエストを受信した場合や、計装がメソッドが事前定義されているかどうかを確実に検出できない場合、この属性は _OTHER に設定しなければなりません（MUST）。
RPC計装が有効なRPCメソッドを _OTHER に変換してしまう可能性がある場合、既知のRPCメソッドの一覧を設定する方法を提供すべきです（SHOULD）。
rpc.method は、実装しているメソッド・関数の名前とは異なることがあります。
code.function.name 属性は、サーバー側で実際に呼び出しを実行している完全修飾メソッド、またはクライアント側のRPCクライアントスタブメソッドを記録するために使用できます。
[3] rpc.response.status_code: 次のエラーコードはエラーとみなすべきです（SHOULD）。
unknowndeadline_exceededunimplementedinternalunavailabledata_loss
[4] server.address: DNS名、サービスレジストリ内のエンドポイントとパス、ローカルソケット名、またはIPアドレスを含む場合があります。
個々のRPCシステムに関するセマンティック規約は、この属性への値の設定方法を文書化すべきです（SHOULD）。
アドレスがIPアドレスである場合、計装はDNS名を得るための逆引きDNSルックアップを行うべきではなく（SHOULD NOT）、server.address を提供されたIPアドレスに設定すべきです（SHOULD）。
[5] server.port: クライアント側から観測され、かつ中間装置を介して通信している場合、server.port は利用可能であれば、プロキシなどの中間装置の背後にあるサーバーのポートを表すべきです（SHOULD）。
[6] network.peer.address: RPCが複数のネットワーク呼び出しを含む場合（例えば再試行）、最後に接続したアドレスを使用すべきです（SHOULD）。
[7] 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）。
[8] 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 | 計装が独自の値を定義していない場合に使うフォールバックのエラー値。 | |
Metrics
Connect RPCの計装は、RPCメトリクスに関するセマンティック規約の全般的な規約に従ってメトリクスを収集すべきです（SHOULD）。
rpc.system.name は "connectrpc" に設定しなければなりません（MUST）。