OpenTelemetryとgRPCのセマンティック規約の間の互換性

gRPCプロジェクトは、OpenTelemetry Metricsの規約と、OpenTelemetry Tracingの実験的な規約を定義しています。

これらの規約は、このリポジトリでホストされているOpenTelemetry gRPCの規約とは異なります。

この文書では、このリポジトリでホストされているOpenTelemetryの規約と、gRPCネイティブの規約との間のマッピング（該当する場合）を示します。

メトリクス

詳細については、gRPCの規約とOpenTelemetryの規約を参照してください。

メトリクスのマッピング

gRPCのメトリクス	OpenTelemetryのメトリクス	変換に関する補足
`grpc.client.call.duration`	`rpc.client.call.duration`	属性のマッピングを下記参照。それ以外はメトリクスとして等価
`grpc.server.call.duration`	`rpc.server.call.duration`	属性のマッピングを下記参照。それ以外はメトリクスとして等価
`grpc.client.attempt.started`	対応するものなし
`grpc.client.attempt.duration`	対応するものなし
`grpc.client.attempt.sent_total_compressed_message_size`	対応するものなし
`grpc.client.attempt.rcvd_total_compressed_message_size`	対応するものなし
`grpc.server.call.started`	対応するものなし
`grpc.server.call.sent_total_compressed_message_size`	対応するものなし
`grpc.server.call.rcvd_total_compressed_message_size`	対応するものなし

属性のマッピング

gRPCの属性	OpenTelemetryの属性	変換に関する補足
`grpc.method`	`rpc.method`	gRPC → OTel: 値が`other`の場合、`_OTHER`に置き換える OTel → gRPC: 値が`_OTHER`の場合、`other`に置き換える
`grpc.status`	`rpc.response.status_code`
`grpc.target`		gRPC → OTel: 削除する OTel → gRPC: `grpc.target`を`{server.address}[:{server.port}]`に設定する
	`server.address`と`server.port`	gRPC → OTel: `grpc.target`からアドレスとポートを解析する OTel → gRPC: 削除する
	`rpc.system.name`	gRPC → OTel: `grpc`に設定する OTel → gRPC: 削除する
	`error.type`	gRPC → OTel: エラーを示す場合は`rpc.response.status_code`に設定する（gRPCのOpenTelemetry規約を参照） OTel → gRPC: 削除する

スパン

詳細については、gRPCの規約とOpenTelemetryの規約を参照してください。

gRPCの規約では、client（クライアント）スパンを call と attempt の2種類に定義しています。gRPCのcallスパンは、OpenTelemetryのRPCクライアントスパンに対応します。どちらのスパン種別も、クライアント呼び出し全体のエンドツーエンドの期間をカバーします。OpenTelemetryは、試行単位のスパンを定義していません。

server（サーバー）スパンについては、gRPCとOpenTelemetryのどちらの規約も、呼び出しごとに1つのサーバースパンを定義しています。

マッピング

プロパティ	gRPC	OpenTelemetry	変換に関する補足
スパン名	`Sent.{method name}`（クライアント） `Recv.{method name}`（サーバー）注: エッジケースでは、gRPCのスパン名のカーディナリティが高くなる可能性があります。	`{rpc.method}`	gRPC → OTel: `Sent.`または`Recv.`の接頭辞を除去する OTel → gRPC: スパン種別に基づいて接頭辞を追加する
スパンステータスコード	レスポンスステータスコードが`OK`でない場合に`ERROR`	特定のエラーステータスコードに対して`ERROR`（gRPCのOpenTelemetry規約を参照）	gRPC → OTel: ステータス記述から`rpc.response.status_code`を解析し、それに応じてスパンステータスコードを設定する OTel → gRPC: `rpc.response.status_code`に基づいて設定する
スパンステータスの記述	コードと記述（例: `UNAVAILABLE, unable to resolve host`）	記述のみ（エラーコードは別に記録される）
属性		`rpc.system.name`	gRPC → OTel: `grpc`に設定する OTel → gRPC: 削除する
		`rpc.method`	gRPC → OTel: スパン名から解析する OTel → gRPC: 削除する
		`rpc.response.status_code`	gRPC → OTel: ステータス記述から解析する OTel → gRPC: 削除する

追加の属性

OpenTelemetryでは、以下に挙げるgRPCスパンの追加属性（必須ではないもの）をいくつか定義しています。gRPCスパンからOpenTelemetryスパンへ変換する際は、これらの属性を設定すべきではありません。OpenTelemetryからgRPCへ変換する際は、これらを保持すべきです。

network.peer.address
network.peer.port
server.address
server.port
rpc.request.metadata.<key>とrpc.response.metadata.<key>
rpc.method_original

イベント

gRPCのスパンには追加のイベントが含まれることがあり、OpenTelemetryへ変換する際はそのまま記録すべきです。