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

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

RPCスパンに関するセマンティック規約

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

この文書では、リモートプロシージャコール（「リモートメソッド呼び出し」/「RMI」とも呼ばれます）をスパンで記述する方法を定義します。

[!IMPORTANT] この文書のv1.37.0 以前のバージョンを使っている既存のRPC計装は、次に従うべきです。
既存のメジャーバージョンにおいて、デフォルトで発行するRPC規約のバージョンを変更してはなりません（SHOULD NOT）。規約には、属性、メトリクス名、スパン名、計測単位などが含まれますが、これらに限定されません。
既存のメジャーバージョンにおいて、カテゴリー別の値をカンマ区切りで列挙するリストとして環境変数 OTEL_SEMCONV_STABILITY_OPT_IN を導入すべきです（SHOULD）（例: http、databases、rpc）。値の一覧は次のとおりです。
rpc - 安定版のRPC規約を発行し、それまで計装が発行していた実験的なRPC規約の発行を停止します。
rpc/dup - 実験的な規約と安定版の規約の両方を発行し、安定版セマンティック規約への段階的な移行を可能にします。
これらの値がいずれも指定されていない場合のデフォルトの動作は、計装がそれまで発行していた古い実験的なRPC規約のバージョンを発行し続けることです。
注: 両方の値が存在する場合、rpc/dup は rpc よりも優先されます。
両方の規約セットを発行し始めてから少なくとも6か月間は、既存のメジャーバージョンを（少なくともセキュリティパッチの適用という形で）維持すべきです（SHOULD）。
次のメジャーバージョンでは、この環境変数を削除し、安定版のRPC規約のみを発行してもかまいません（MAY）。

名前

RPCスパンは、スパン名に関する全般的なガイドラインに従わなければなりません（MUST）。

スパン名は、rpc.method が利用可能で _OTHER に設定されていない場合、{rpc.method} であるべきです（SHOULD）。

rpc.method が利用できないか _OTHER に設定されている場合、スパン名は {rpc.system.name} であるべきです（SHOULD）。

個々のRPCシステムに関するセマンティック規約は、異なるスパン名の形式を指定してもかまいません（MAY）。

RPCクライアントスパン

Status:

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

RPCクライアントスパンは、RPCが開始してからレスポンスを受信するか、エラーやキャンセルによってRPCが終了するまでの、クライアント側のライフサイクル全体をカバーすべきです（SHOULD）。

ストリーミングRPCの場合、スパンはリクエストストリームおよび／またはレスポンスストリームがクローズまたは終了するまでの全期間をカバーします。

このRPCの中で一時的な問題が発生し再試行された場合、対応するスパンはすべての再試行を含む論理的な呼び出しの期間をカバーすべきです（SHOULD）。

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

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

Span status: スパンステータスの記録方法の詳細については、エラーの記録を参照してください。

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`rpc.system.name`	`Required`	string	リモートプロシージャコール（RPC）システム。[1]	`grpc`; `dubbo`; `connectrpc`
`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	RPCサーバーが返した、またはクライアントが生成した、RPCのステータスコード。[4]	`OK`; `DEADLINE_EXCEEDED`; `-32602`
`server.address`	`Conditionally Required` 利用可能な場合。	string	リクエストの送信先であるRPCサーバーインスタンスのグループを識別する文字列。[5]	`example.com`; `10.1.2.80`; `/tmp/my.sock`
`server.port`	`Conditionally Required` 適用可能であり、かつ `server.address` が設定されている場合。	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`

[1] rpc.system.name: 同じRPCのやり取りでも、クライアントとサーバーのRPCシステムが異なる場合があります。例えば、クライアントはApache DubboやConnect RPCを使ってgRPCを使用するサーバーと通信することがあります。どちらのプロトコルもgRPCとの互換性を提供しているためです。

[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: 通常はエラーコードを表しますが、部分的な成功や警告を表す場合や、さまざまな種類の成功結果を区別する場合もあります。個々のRPCフレームワークに関するセマンティック規約は、そのシステムの文脈における rpc.response.status_code の意味と、どの値がエラーを表すとみなされるかを文書化すべきです（SHOULD）。

[5] server.address: DNS名、サービスレジストリ内のエンドポイントとパス、ローカルソケット名、またはIPアドレスを含む場合があります。個々のRPCシステムに関するセマンティック規約は、この属性への値の設定方法を文書化すべきです（SHOULD）。アドレスがIPアドレスである場合、計装はDNS名を得るための逆引きDNSルックアップを行うべきではなく（SHOULD NOT）、server.address を提供されたIPアドレスに設定すべきです（SHOULD）。

[6] server.port: クライアント側から観測され、かつ中間装置を介して通信している場合、server.port は利用可能であれば、プロキシなどの中間装置の背後にあるサーバーのポートを表すべきです（SHOULD）。

[7] network.peer.address: RPCが複数のネットワーク呼び出しを含む場合（例えば再試行）、最後に接続したアドレスを使用すべきです（SHOULD）。

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

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

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

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

Value	Description	Stability
`connectrpc`	Connect RPC
`dubbo`	Apache Dubbo
`grpc`	gRPC
`jsonrpc`	JSON-RPC

RPCサーバースパン

Status:

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

RPCサーバースパンは、リクエストを受信してからレスポンスを送信するか、エラーやキャンセルによってRPCが終了するまでの、サーバー側のライフサイクル全体をカバーすべきです（SHOULD）。

ストリーミングRPCの場合、スパンはリクエストストリームおよび／またはレスポンスストリームがクローズまたは終了するまでの全期間をカバーすべきです（SHOULD）。