JSON-RPCに関するセマンティック規約

ステータス: Development

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

Spans

Client

Status:

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

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

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

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

Span status: スパンステータスの記録方法の詳細については、エラーの記録を参照してください。errorオブジェクトを含むレスポンスはエラーとみなされます。

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`error.type`	`Conditionally Required` 操作が失敗した場合に限る。	string	操作が終了したエラーのクラスを記述します。[1]	`DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602`
`jsonrpc.protocol.version`	`Conditionally Required` デフォルトのバージョン（`1.0`）以外の場合。	string	リクエストとそれに対応するレスポンスの `jsonrpc` プロパティで指定されるプロトコルバージョン。	`2.0`; `1.0`
`rpc.method_original`	`Conditionally Required` `rpc.method` と異なる場合に限る。	string	クライアントが使用した元のメソッド名。	`com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod`
`rpc.response.status_code`	`Conditionally Required` 利用可能な場合。	string	エラーレスポンスである場合の、レスポンスの`error.code`プロパティを文字列として記録した値。[2]	`OK`; `DEADLINE_EXCEEDED`; `-32602`
`server.port`	`Conditionally Required` 適用可能であり、かつ `server.address` が設定されている場合。	int	サーバーのポート番号。[3]	`80`; `8080`; `443`
`jsonrpc.request.id`	`Recommended`	string	リクエストとそれに対応するレスポンスの `id` プロパティの文字列表現。[4]	`10`; `request-7`
`network.peer.address`	`Recommended`	string	ネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。[5]	`10.1.2.80`; `/tmp/my.sock`
`network.peer.port`	`Recommended` `network.peer.address` が設定されている場合。	int	ネットワーク接続のピアポート番号。	`65123`
`server.address`	`Recommended` [6]	string	リクエストの送信先であるRPCサーバーインスタンスのグループを識別する文字列。	`example.com`; `10.1.2.80`; `/tmp/my.sock`
`rpc.method`	`Opt-In`	string	リクエストで提供されたJSON-RPCメソッド名。[7]	`com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER`

[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.response.status_code: すべてのJSON RPCエラーコードはエラーとみなすべきです（SHOULD）。

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

[4] jsonrpc.request.id: JSON-RPC仕様の下では、id プロパティは文字列、数値、null、または省略のいずれかを取り得ます。省略された場合、リクエストは通知として扱われます。null を使うことは id を省略することと同義ではありませんが、非推奨とされています。計装は、id が null であるか省略されている場合、この属性を取得すべきではありません（SHOULD NOT）。

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

[6] server.address: トランスポート層の情報にアクセスでき、そこからドメイン名や他の低カーディナリティなサーバーアドレスを確実に抽出できる計装は、この属性を設定すべきです（SHOULD）。

[7] rpc.method: JSON-RPCは、事前の登録や定義なしに任意のメソッド名を送受信することをサポートしています。その結果、メソッド名はエッジケースやエラーケースにおいて無制限のカーディナリティを持つことがあります（MAY）。そのため、汎用的なJSON-RPC計装はデフォルトでこの属性を設定すべきではなく（SHOULD NOT）、既知のRPCメソッドの一覧を設定する方法を提供すべきです（SHOULD）。トレース計装がRPCメソッドを _OTHER に変換する場合、rpc.method_original スパン属性を元の値に設定しなければなりません（MUST）。

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

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

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

Server

Status:

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

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

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

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

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`error.type`	`Conditionally Required` 操作が失敗した場合に限る。	string	操作が終了したエラーのクラスを記述します。[1]	`DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602`
`jsonrpc.protocol.version`	`Conditionally Required` デフォルトのバージョン（`1.0`）以外の場合。	string	リクエストとそれに対応するレスポンスの `jsonrpc` プロパティで指定されるプロトコルバージョン。	`2.0`; `1.0`
`rpc.method_original`	`Conditionally Required` `rpc.method` と異なる場合に限る。	string	クライアントが使用した元のメソッド名。	`com.myservice.EchoService/catchAll`; `com.myservice.EchoService/unknownMethod`; `InvalidMethod`
`rpc.response.status_code`	`Conditionally Required` 利用可能な場合。	string	レスポンスの`error.code`プロパティを文字列として記録した値。[2]	`OK`; `DEADLINE_EXCEEDED`; `-32602`
`server.address`	`Conditionally Required` 利用可能な場合。	string	リクエストの送信先であるRPCサーバーインスタンスのグループを識別する文字列。[3]	`example.com`; `10.1.2.80`; `/tmp/my.sock`
`server.port`	`Conditionally Required` 適用可能であり、かつ `server.address` が設定されている場合。	int	サーバーのポート番号。[4]	`80`; `8080`; `443`
`jsonrpc.request.id`	`Recommended`	string	リクエストとそれに対応するレスポンスの `id` プロパティの文字列表現。[5]	`10`; `request-7`
`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.method`	`Opt-In`	string	リクエストで提供されたJSON-RPCメソッド名。[7]	`com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER`

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

[2] rpc.response.status_code: すべてのJSON RPCエラーコードはエラーとみなすべきです（SHOULD）。

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

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

[5] jsonrpc.request.id: JSON-RPC仕様の下では、id プロパティは文字列、数値、null、または省略のいずれかを取り得ます。省略された場合、リクエストは通知として扱われます。null を使うことは id を省略することと同義ではありませんが、非推奨とされています。計装は、id が null であるか省略されている場合、この属性を取得すべきではありません（SHOULD NOT）。

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

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

Metrics

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

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