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


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

gRPCプロジェクトは、[OpenTelemetry Metrics](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md)の規約と、[OpenTelemetry Tracing](https://github.com/grpc/proposal/blob/master/A72-open-telemetry-tracing.md)の実験的な規約を定義しています。

これらの規約は、このリポジトリでホストされている[OpenTelemetry gRPC](/works/otel-specs-ja/semconv/rpc/grpc/)の規約とは異なります。

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

## メトリクス

詳細については、[gRPCの規約](https://github.com/grpc/proposal/blob/master/A66-otel-stats.md)と[OpenTelemetryの規約](/works/otel-specs-ja/semconv/rpc/rpc-metrics/)を参照してください。

### メトリクスのマッピング

| 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`に置き換える<br>OTel → gRPC: 値が`_OTHER`の場合、`other`に置き換える |
| `grpc.status`      | `rpc.response.status_code`         | |
| `grpc.target`      |                                    | gRPC → OTel: 削除する<br>OTel → gRPC: `grpc.target`を`{server.address}[:{server.port}]`に設定する |
|                    | `server.address`と`server.port` | gRPC → OTel: `grpc.target`からアドレスとポートを解析する<br>OTel → gRPC: 削除する |
|                    | `rpc.system.name`                  | gRPC → OTel: `grpc`に設定する<br>OTel → gRPC: 削除する |
|                    | `error.type`                       | gRPC → OTel: エラーを示す場合は`rpc.response.status_code`に設定する（[gRPCのOpenTelemetry規約](/works/otel-specs-ja/semconv/rpc/grpc/)を参照）<br>OTel → gRPC: 削除する |

## スパン

詳細については、[gRPCの規約](https://github.com/grpc/proposal/blob/master/A72-open-telemetry-tracing.md)と[OpenTelemetryの規約](/works/otel-specs-ja/semconv/rpc/rpc-spans/)を参照してください。

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

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

### マッピング

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