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


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

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

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

> [!IMPORTANT]
> [この文書のv1.37.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/rpc-spans.md)
> 以前のバージョンを使っている既存の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スパンは、[スパン名に関する全般的なガイドライン](/works/otel-specs-ja/spec/trace/api/#span)に従わなければなりません（MUST）。

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

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

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

## RPCクライアントスパン

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

**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid)

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

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

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

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

**Span name:** [名前](#名前)の節を参照してください。

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

**Span status**: スパンステータスの記録方法の詳細については、[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)を参照してください。

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`rpc.system.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | リモートプロシージャコール（RPC）システム。[1] | `grpc`; `dubbo`; `connectrpc` |
| [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` 操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` |
| [`rpc.method`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` 利用可能な場合。 | string | RPCインターフェースの観点から見た、完全修飾されたメソッドの論理名。[3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` |
| [`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 | RPCサーバーが返した、またはクライアントが生成した、RPCのステータスコード。[4] | `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サーバーインスタンスのグループを識別する文字列。[5] | `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 | サーバーのポート番号。[6] | `80`; `8080`; `443` |
| [`network.peer.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | ネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。[7] | `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` |

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

* [`rpc.method`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/)
* [`rpc.system.name`](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) |

---

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

| Value | Description | Stability |
| --- | --- | --- |
| `connectrpc` | [Connect RPC](https://connectrpc.com/) | ![Development](https://img.shields.io/badge/-development-blue) |
| `dubbo` | [Apache Dubbo](https://dubbo.apache.org/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `grpc` | [gRPC](https://grpc.io/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `jsonrpc` | [JSON-RPC](https://www.jsonrpc.org/) | ![Development](https://img.shields.io/badge/-development-blue) |

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

## RPCサーバースパン

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

**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid)

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

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

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

**Span name:** [名前](#名前)の節を参照してください。

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

**Span status**: スパンステータスの記録方法の詳細については、[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)を参照してください。

**Attributes:**

| Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`rpc.system.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | リモートプロシージャコール（RPC）システム。[1] | `grpc`; `dubbo`; `connectrpc` |
| [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` 操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[2] | `DEADLINE_EXCEEDED`; `java.net.UnknownHostException`; `-32602` |
| [`rpc.method`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` 利用可能な場合。 | string | RPCインターフェースの観点から見た、完全修飾されたメソッドの論理名。[3] | `com.example.ExampleService/exampleMethod`; `EchoService/Echo`; `_OTHER` |
| [`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 | RPCサーバーが返した、またはクライアントが生成した、RPCのステータスコード。[4] | `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サーバーインスタンスのグループを識別する文字列。[5] | `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 | サーバーのポート番号。[6] | `80`; `8080`; `443` |
| [`network.peer.address`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | ネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。[7] | `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` |

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

* [`rpc.method`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/rpc/)
* [`rpc.system.name`](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) |

---

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

| Value | Description | Stability |
| --- | --- | --- |
| `connectrpc` | [Connect RPC](https://connectrpc.com/) | ![Development](https://img.shields.io/badge/-development-blue) |
| `dubbo` | [Apache Dubbo](https://dubbo.apache.org/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `grpc` | [gRPC](https://grpc.io/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) |
| `jsonrpc` | [JSON-RPC](https://www.jsonrpc.org/) | ![Development](https://img.shields.io/badge/-development-blue) |

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

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