> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/rpc/json-rpc/


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

**ステータス**: [Development][DocumentStatus]

[JSON-RPC](https://www.jsonrpc.org/)に関するセマンティック規約は、[RPCセマンティック規約](/works/otel-specs-ja/semconv/rpc/)を拡張・上書きします。

## Spans

### Client

<!-- semconv span.rpc.jsonrpc.call.client -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

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

`rpc.system.name` は `"jsonrpc"` に設定しなければならず（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/)を参照してください。[`error`オブジェクト](https://www.jsonrpc.org/specification#error_object)を含むレスポンスはエラーとみなされます。

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` 操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[1] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` |
| [`jsonrpc.protocol.version`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/jsonrpc/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` デフォルトのバージョン（`1.0`）以外の場合。 | string | リクエストとそれに対応するレスポンスの `jsonrpc` プロパティで指定されるプロトコルバージョン。 | `2.0`; `1.0` |
| [`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` |
| [`rpc.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` 利用可能な場合。 | string | エラーレスポンスである場合の、レスポンスの[`error.code`](https://www.jsonrpc.org/specification#error_object)プロパティを文字列として記録した値。[2] | `OK`; `DEADLINE_EXCEEDED`; `-32602` |
| [`server.port`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` 適用可能であり、かつ `server.address` が設定されている場合。 | int | サーバーのポート番号。[3] | `80`; `8080`; `443` |
| [`jsonrpc.request.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/jsonrpc/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | リクエストとそれに対応するレスポンスの `id` プロパティの文字列表現。[4] | `10`; `request-7` |
| [`network.peer.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | ネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。[5] | `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` |
| [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` [6] | string | リクエストの送信先であるRPCサーバーインスタンスのグループを識別する文字列。 | `example.com`; `10.1.2.80`; `/tmp/my.sock` |
| [`rpc.method`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `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仕様](https://www.jsonrpc.org/specification)の下では、`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）。

* [`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) |

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

### Server

<!-- semconv span.rpc.jsonrpc.call.server -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

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

`rpc.system.name` は `"jsonrpc"` に設定しなければならず（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/)を参照してください。[`error`オブジェクト](https://www.jsonrpc.org/specification#error_object)を含むレスポンスはエラーとみなされます。

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` 操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[1] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` |
| [`jsonrpc.protocol.version`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/jsonrpc/) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` デフォルトのバージョン（`1.0`）以外の場合。 | string | リクエストとそれに対応するレスポンスの `jsonrpc` プロパティで指定されるプロトコルバージョン。 | `2.0`; `1.0` |
| [`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` |
| [`rpc.response.status_code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` 利用可能な場合。 | string | レスポンスの[`error.code`](https://www.jsonrpc.org/specification#error_object)プロパティを文字列として記録した値。[2] | `OK`; `DEADLINE_EXCEEDED`; `-32602` |
| [`server.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/server/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` 利用可能な場合。 | string | リクエストの送信先であるRPCサーバーインスタンスのグループを識別する文字列。[3] | `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` 適用可能であり、かつ `server.address` が設定されている場合。 | int | サーバーのポート番号。[4] | `80`; `8080`; `443` |
| [`jsonrpc.request.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/jsonrpc/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | リクエストとそれに対応するレスポンスの `id` プロパティの文字列表現。[5] | `10`; `request-7` |
| [`network.peer.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | ネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。[6] | `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.method`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `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.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仕様](https://www.jsonrpc.org/specification)の下では、`id` プロパティは文字列、数値、null、または省略のいずれかを取り得ます。省略された場合、リクエストは通知として扱われます。`null` を使うことは `id` を省略することと同義ではありませんが、非推奨とされています。
計装は、`id` が `null` であるか省略されている場合、この属性を取得すべきではありません（SHOULD NOT）。

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

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

次の属性は、サンプリングの判断を行う上で重要になる場合があり、（何であれ提供する場合には）**スパン作成時点**で提供されるべきです（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) |

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

## Metrics

JSON-RPCの計装は、[RPCメトリクスに関するセマンティック規約](/works/otel-specs-ja/semconv/rpc/rpc-metrics/)の全般的な規約に従ってメトリクスを収集すべきです（SHOULD）。

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

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status