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からTODO（最新版）への変更をまとめます。

RPCのスパン属性

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

参考:

`rpc.system.name`の値

Change	PR	Comments
`apache_dubbo` → `dubbo`	#3176
`connect_rpc` → `connectrpc`	#3176
`java_rmi`	#3176	削除。ただしカスタム値としては引き続き使用できる
`dotnet_wcf`	#3176	削除。ただしカスタム値としては引き続き使用できる
新規: `jsonrpc`	#2503

参考:

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

メトリクスの変更点:

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

Attribute change	PR	Comments
`rpc.system` → `rpc.system.name`	#3176	値の変更については上記を参照
`rpc.method`	#3223	完全修飾のメソッド名（例: `com.example.ExampleService/exampleMethod`）を含むようになった
`rpc.service`	#3223	削除、`rpc.method`に統合
`network.transport`	#3350	削除
`network.type`	#2857	削除
`server.address`	#3197	RecommendedからOpt-Inに変更
`server.port`	#3197	RecommendedからOpt-Inに変更
新規: `rpc.response.status_code`	#2920
新規: `error.type`	#2852

参考:

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

メトリクスの変更点:

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

Attribute change	PR	Comments
`rpc.system` → `rpc.system.name`	#3176	値の変更については上記を参照
`rpc.method`	#3223	完全修飾のメソッド名（例: `com.example.ExampleService/exampleMethod`）を含むようになった
`rpc.service`	#3223	削除、`rpc.method`に統合
`network.transport`	#3350	削除
`network.type`	#2857	削除
`server.address`	#3197	RecommendedからRequiredに変更
`server.port`	#3197	RecommendedからConditionally Requiredに変更
新規: `rpc.response.status_code`	#2920
新規: `error.type`	#2852

参考:

RPCの例外イベント

呼び出しが正常に完了することを妨げる例外は、rpc.client.call.exceptionとrpc.server.call.exceptionというログベースのイベントとして記録されます（#3426）。

非推奨になったイベント

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

Deprecated Event/Attribute	PR
`rpc.message`イベント	#3283
`rpc.message.type`	#3283
`rpc.message.id`	#3283
`rpc.message.compressed_size`	#3283
`rpc.message.uncompressed_size`	#3283

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

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

Deprecated Metric	PR
`rpc.server.requests_per_rpc`	#2846
`rpc.server.responses_per_rpc`	#2846
`rpc.client.requests_per_rpc`	#2846
`rpc.client.responses_per_rpc`	#2846
`rpc.server.request.size`	#3267
`rpc.server.response.size`	#3267
`rpc.client.request.size`	#3267
`rpc.client.response.size`	#3267