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


# RPCセマンティック規約の安定性に関する移行ガイド

> [!WARNING]
> RPCセマンティック規約はまだ安定版としてマークされておらず、変更が続いているため、この文書は作業中です。

変更点の量が多く、影響を受けるユーザー基盤も広範であることから、OpenTelemetryが公開している既存のRPC計装は、安定版のRPCセマンティック規約への移行をユーザーが行いやすくする移行計画を実装する必要があります。

具体的には、OpenTelemetryが公開している既存のRPC計装が安定版のRPCセマンティック規約に更新される際には、次のようにします。

- 既存のメジャーバージョンにおいて、デフォルトで発行するRPC規約のバージョンを変更してはなりません（SHOULD NOT）。規約には、属性、メトリクス名、スパン名、計測単位などが含まれますが、これらに限定されません。
- 既存のメジャーバージョンにおいて、環境変数`OTEL_SEMCONV_STABILITY_OPT_IN`を導入すべきです（SHOULD）。この変数は次の値を受け付けます。
  - `rpc` - 安定版のRPC規約を発行し、それまで計装が発行していた古いRPC規約の発行を停止します。
  - `rpc/dup` - 古い規約と安定版の規約の両方を発行し、安定版セマンティック規約への段階的な移行を可能にします。
  - これらの値がいずれも指定されていない場合のデフォルトの動作は、その計装がそれまで発行していた古いRPC規約のバージョンをそのまま発行し続けることです。
- 両方の規約セットを発行し始めてから少なくとも6か月間は、既存のメジャーバージョンを（少なくともセキュリティパッチの適用という形で）維持する必要があります。
- 次のメジャーバージョンでは、この環境変数を削除し、安定版のRPC規約のみを発行してもかまいません（MAY）。

> [!NOTE]
> `OTEL_SEMCONV_STABILITY_OPT_IN`は、実験的なセマンティック規約から最初の安定版への移行時にのみ使用することを意図しています。

## 変更点のまとめ

この節では、RPCセマンティック規約について、[v1.37.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/README.md)からTODO（最新版）への変更をまとめます。

### RPCのスパン属性

<!-- disable markdownlint requirement for tables to be aligned -->
<!-- markdownlint-disable-file MD060 -->
<!-- prettier-ignore-start -->
| Change                                                         | PR                                                                                                                                                   | Comments                                                                                                                          |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `rpc.system` &rarr; `rpc.system.name`                          | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176), [#3203](https://github.com/open-telemetry/semantic-conventions/pull/3203) | 値の変更については[下記](#rpcsystemnameの値)を参照。サンプリングに関係する属性としてもマークされるようになった                                |
| `rpc.method`                                                   | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223), [#3203](https://github.com/open-telemetry/semantic-conventions/pull/3203) | 完全修飾のメソッド名（例: `com.example.ExampleService/exampleMethod`）を含むようになり、サンプリングに関係する属性としてもマークされるようになった |
| `rpc.service`                                                  | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223)                                                                            | 削除、`rpc.method`に統合                                                                                             |
| `network.transport`                                            | [#3350](https://github.com/open-telemetry/semantic-conventions/pull/3350)                                                                            | 削除                                                                                                                           |
| `network.type`                                                 | [#2857](https://github.com/open-telemetry/semantic-conventions/pull/2857)                                                                            | 削除                                                                                                                           |
| `rpc.grpc.status_code` &rarr; `rpc.response.status_code`       | [#2920](https://github.com/open-telemetry/semantic-conventions/pull/2920)                                                                            | intからstringに変更（例: `0` &rarr; `"OK"`）                                                                              |
| `rpc.connect_rpc.error_code` &rarr; `rpc.response.status_code` | [#2920](https://github.com/open-telemetry/semantic-conventions/pull/2920)                                                                            |                                                                                                                                   |
| `rpc.grpc.request.metadata.<key>`                              | [#3169](https://github.com/open-telemetry/semantic-conventions/pull/3169)                                                                            | `rpc.request.metadata.<key>`に置き換え                                                                                          |
| `rpc.grpc.response.metadata.<key>`                             | [#3169](https://github.com/open-telemetry/semantic-conventions/pull/3169)                                                                            | `rpc.response.metadata.<key>`に置き換え                                                                                         |
| `rpc.connect_rpc.request.metadata.<key>`                       | [#3169](https://github.com/open-telemetry/semantic-conventions/pull/3169)                                                                            | `rpc.request.metadata.<key>`に置き換え                                                                                          |
| `rpc.connect_rpc.response.metadata.<key>`                      | [#3169](https://github.com/open-telemetry/semantic-conventions/pull/3169)                                                                            | `rpc.response.metadata.<key>`に置き換え                                                                                         |
| `server.address`                                               | [#3203](https://github.com/open-telemetry/semantic-conventions/pull/3203), [#3317](https://github.com/open-telemetry/semantic-conventions/pull/3317) | サンプリングに関係する属性としてマークされるようになった。<br>静的な設定から取得するようになり、サーバーインスタンスのグループを識別する任意の文字列を使用できる。  |
| `server.port`                                                  | [#3203](https://github.com/open-telemetry/semantic-conventions/pull/3203), [#3317](https://github.com/open-telemetry/semantic-conventions/pull/3317) | サンプリングに関係する属性としてマークされるようになった。<br>静的な設定から取得するようになった。  |
| 新規: `error.type`                                              | [#2852](https://github.com/open-telemetry/semantic-conventions/pull/2852)                                                                            |                                                                                                                                   |
| 新規: `rpc.method_original`                                     | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223)                                                                            | `rpc.method`が`_OTHER`に設定されている場合の元のメソッド名                                                                         |
| `client.address`                                               | [#3488](https://github.com/open-telemetry/semantic-conventions/pull/3488)                                                                            | 削除                                                                                                                           |
| `client.port`                                                  | [#3488](https://github.com/open-telemetry/semantic-conventions/pull/3488)                                                                            | 削除                                                                                                                           |

<!-- prettier-ignore-end -->

参考:

- [RPCのスパン v1.37.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/rpc-spans.md)
- [RPCのスパン（TODO）](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-spans.md)

### `rpc.system.name`の値

<!-- prettier-ignore-start -->
| Change                            | PR                                                                        | Comments                                         |
| --------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------ |
| `apache_dubbo` &rarr; `dubbo`     | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176) |                                                  |
| `connect_rpc` &rarr; `connectrpc` | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176) |                                                  |
| `java_rmi`                        | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176) | 削除。ただしカスタム値としては引き続き使用できる |
| `dotnet_wcf`                      | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176) | 削除。ただしカスタム値としては引き続き使用できる |
| 新規: `jsonrpc`                    | [#2503](https://github.com/open-telemetry/semantic-conventions/pull/2503) |                                                  |
<!-- prettier-ignore-end -->

参考:

- [RPCのスパン v1.37.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/rpc-spans.md)
- [RPCのスパン（TODO）](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-spans.md)

### RPCサーバーの呼び出し時間メトリクス

メトリクスの変更点:

- **名前**: `rpc.server.duration` &rarr; `rpc.server.call.duration`（[#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)）
- **単位**: `ms` &rarr; `s`（[#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)）
- **説明**: `Measures the duration of inbound RPC.` &rarr;
  `Measures the duration of inbound remote procedure calls (RPC).`（[#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)）
- **ヒストグラムのバケット**: ミリ秒から秒への変更を反映して境界値を更新（[#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)）
- **要求レベル**: 必須になった（[#3284](https://github.com/open-telemetry/semantic-conventions/pull/3284)）
- **属性**: 以下の表を参照

<!-- prettier-ignore-start -->
| Attribute change                      | PR                                                                        | Comments                                                                                    |
| ------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `rpc.system` &rarr; `rpc.system.name` | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176) | 値の変更については[上記](#rpcsystemnameの値)を参照                                |
| `rpc.method`                          | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223) | 完全修飾のメソッド名（例: `com.example.ExampleService/exampleMethod`）を含むようになった |
| `rpc.service`                         | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223) | 削除、`rpc.method`に統合                                                       |
| `network.transport`                   | [#3350](https://github.com/open-telemetry/semantic-conventions/pull/3350) | 削除                                                                                     |
| `network.type`                        | [#2857](https://github.com/open-telemetry/semantic-conventions/pull/2857) | 削除                                                                                     |
| `server.address`                      | [#3197](https://github.com/open-telemetry/semantic-conventions/pull/3197) | RecommendedからOpt-Inに変更                                                          |
| `server.port`                         | [#3197](https://github.com/open-telemetry/semantic-conventions/pull/3197) | RecommendedからOpt-Inに変更                                                          |
| 新規: `rpc.response.status_code`       | [#2920](https://github.com/open-telemetry/semantic-conventions/pull/2920) |                                                                                             |
| 新規: `error.type`                     | [#2852](https://github.com/open-telemetry/semantic-conventions/pull/2852) |                                                                                             |
<!-- prettier-ignore-end -->

参考:

- [メトリクス`rpc.server.duration` v1.37.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/rpc-metrics.md#metric-rpcserverduration)
- [メトリクス`rpc.server.call.duration`（TODO）](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-metrics.md#metric-rpcservercallduration)

### RPCクライアントの呼び出し時間メトリクス

メトリクスの変更点:

- **名前**: `rpc.client.duration` &rarr; `rpc.client.call.duration`（[#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)）
- **単位**: `ms` &rarr; `s`（[#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)）
- **説明**: `Measures the duration of outbound RPC.` &rarr;
  `Measures the duration of outbound remote procedure calls (RPC).`（[#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)）
- **ヒストグラムのバケット**: ミリ秒から秒への変更を反映して境界値を更新（[#2961](https://github.com/open-telemetry/semantic-conventions/pull/2961)）
- **要求レベル**: 必須になった（[#3284](https://github.com/open-telemetry/semantic-conventions/pull/3284)）
- **属性**: 以下の表を参照

<!-- prettier-ignore-start -->
| Attribute change                      | PR                                                                        | Comments                                                                                    |
| ------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `rpc.system` &rarr; `rpc.system.name` | [#3176](https://github.com/open-telemetry/semantic-conventions/pull/3176) | 値の変更については[上記](#rpcsystemnameの値)を参照                                |
| `rpc.method`                          | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223) | 完全修飾のメソッド名（例: `com.example.ExampleService/exampleMethod`）を含むようになった |
| `rpc.service`                         | [#3223](https://github.com/open-telemetry/semantic-conventions/pull/3223) | 削除、`rpc.method`に統合                                                       |
| `network.transport`                   | [#3350](https://github.com/open-telemetry/semantic-conventions/pull/3350) | 削除                                                                                     |
| `network.type`                        | [#2857](https://github.com/open-telemetry/semantic-conventions/pull/2857) | 削除                                                                                     |
| `server.address`                      | [#3197](https://github.com/open-telemetry/semantic-conventions/pull/3197) | RecommendedからRequiredに変更                                                        |
| `server.port`                         | [#3197](https://github.com/open-telemetry/semantic-conventions/pull/3197) | RecommendedからConditionally Requiredに変更                                          |
| 新規: `rpc.response.status_code`       | [#2920](https://github.com/open-telemetry/semantic-conventions/pull/2920) |                                                                                             |
| 新規: `error.type`                     | [#2852](https://github.com/open-telemetry/semantic-conventions/pull/2852) |                                                                                             |
<!-- prettier-ignore-end -->

参考:

- [メトリクス`rpc.client.duration` v1.37.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/rpc/rpc-metrics.md#metric-rpcclientduration)
- [メトリクス`rpc.client.call.duration`（TODO）](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/rpc-metrics.md#metric-rpcclientcallduration)

### RPCの例外イベント

呼び出しが正常に完了することを妨げる例外は、[`rpc.client.call.exception`と`rpc.server.call.exception`というログベースのイベント](/works/otel-specs-ja/semconv/rpc/rpc-exceptions/)として記録されます（[#3426](https://github.com/open-telemetry/semantic-conventions/pull/3426)）。

### 非推奨になったイベント

`rpc.message`イベントとそれに関連する属性は、代替なしで非推奨になりました。

<!-- prettier-ignore-start -->
| Deprecated Event/Attribute     | PR                                                                        |
| ------------------------------ | ------------------------------------------------------------------------- |
| `rpc.message`イベント            | [#3283](https://github.com/open-telemetry/semantic-conventions/pull/3283) |
| `rpc.message.type`             | [#3283](https://github.com/open-telemetry/semantic-conventions/pull/3283) |
| `rpc.message.id`               | [#3283](https://github.com/open-telemetry/semantic-conventions/pull/3283) |
| `rpc.message.compressed_size`  | [#3283](https://github.com/open-telemetry/semantic-conventions/pull/3283) |
| `rpc.message.uncompressed_size`| [#3283](https://github.com/open-telemetry/semantic-conventions/pull/3283) |
<!-- prettier-ignore-end -->

### 非推奨になったメトリクス

以下のメトリクスは、代替なしで非推奨になりました。

<!-- prettier-ignore-start -->
| Deprecated Metric              | PR                                                                        |
| ------------------------------ | ------------------------------------------------------------------------- |
| `rpc.server.requests_per_rpc`  | [#2846](https://github.com/open-telemetry/semantic-conventions/pull/2846) |
| `rpc.server.responses_per_rpc` | [#2846](https://github.com/open-telemetry/semantic-conventions/pull/2846) |
| `rpc.client.requests_per_rpc`  | [#2846](https://github.com/open-telemetry/semantic-conventions/pull/2846) |
| `rpc.client.responses_per_rpc` | [#2846](https://github.com/open-telemetry/semantic-conventions/pull/2846) |
| `rpc.server.request.size`      | [#3267](https://github.com/open-telemetry/semantic-conventions/pull/3267) |
| `rpc.server.response.size`     | [#3267](https://github.com/open-telemetry/semantic-conventions/pull/3267) |
| `rpc.client.request.size`      | [#3267](https://github.com/open-telemetry/semantic-conventions/pull/3267) |
| `rpc.client.response.size`     | [#3267](https://github.com/open-telemetry/semantic-conventions/pull/3267) |
<!-- prettier-ignore-end -->