この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/semconv/rpc/rpc-metrics/
翻訳元: open-telemetry/semantic-conventions v1.44.0（コミット e10a930）
RPCメトリクスに関するセマンティック規約
ステータス: Release Candidate（特に断りがない限り）
この節で説明する規約はRPC固有のものです。RPC操作が発生すると、それらの操作に関する測定値がInstrumentに記録されます。測定値は集計されてメトリクスとしてエクスポートされ、それらの操作に対する洞察を提供します。RPCのプロパティを測定値の属性として含めることで、メトリクスをより詳細な分析のためにフィルタリングできます。
[!IMPORTANT] この文書のv1.37.0 以前のバージョンを使っている既存の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サーバーとクライアントのメトリクスは、クライアント／サーバー境界をまたいだ相関を可能にするために分割されています。例えば、サーバーが原因のレイテンシーなのか、クライアントが観測しているレイテンシーなのかを判断するために、RPCメソッドのレイテンシーを突き合わせる場合などです。
RPCサーバー
メトリクス: rpc.server.call.duration
このメトリクスは推奨（recommended）です。
このメトリクスは、
ExplicitBucketBoundaries
を [ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ] として指定すべきです（SHOULD）。
| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
|---|---|---|---|---|---|
rpc.server.call.duration | Histogram | s | 受信するリモートプロシージャコール（RPC）の期間を測定します。[1] |  |
[1]: このメトリクスがRPCサーバースパンと併せて報告される場合、メトリクスの値はRPCサーバースパンの期間と同じであるべきです（SHOULD）。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
rpc.system.name | | Required | string | リモートプロシージャコール（RPC）システム。[1] | grpc; dubbo; connectrpc |
error.type |  | Conditionally Required 操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[2] | DEADLINE_EXCEEDED; java.net.UnknownHostException; -32602 |
rpc.method | | Conditionally Required 利用可能な場合。 | string | RPCインターフェースの観点から見た、完全修飾されたメソッドの論理名。[3] | com.example.ExampleService/exampleMethod; EchoService/Echo; _OTHER |
rpc.response.status_code | | Conditionally Required 利用可能な場合。 | string | RPCサーバーが返した、またはクライアントが生成した、RPCのステータスコード。[4] | OK; DEADLINE_EXCEEDED; -32602 |
server.address | | Opt-In | string | リクエストの送信先であるRPCサーバーインスタンスのグループを識別する文字列。 | example.com; 10.1.2.80; /tmp/my.sock |
server.port | | Opt-In | int | サーバーのポート番号。 | 80; 8080; 443 |
[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）。
error.type には、次の既知の値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、そうでない場合は独自の値を使用してもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
_OTHER | 計装が独自の値を定義していない場合に使うフォールバックのエラー値。 | |
rpc.system.name には、次の既知の値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、そうでない場合は独自の値を使用してもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
connectrpc | Connect RPC |  |
dubbo | Apache Dubbo | |
grpc | gRPC | |
jsonrpc | JSON-RPC | |
RPCクライアント
メトリクス: rpc.client.call.duration
このメトリクスは推奨（recommended）です。
このメトリクスは、
ExplicitBucketBoundaries
を [ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ] として指定すべきです（SHOULD）。
| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
|---|---|---|---|---|---|
rpc.client.call.duration | Histogram | s | 送信するリモートプロシージャコール（RPC）の期間を測定します。[1] | |
[1]: このメトリクスがRPCクライアントスパンと併せて報告される場合、メトリクスの値はRPCクライアントスパンの期間と同じであるべきです（SHOULD）。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
rpc.system.name | | Required | string | リモートプロシージャコール（RPC）システム。[1] | grpc; dubbo; connectrpc |
error.type | | Conditionally Required 操作が失敗した場合に限る。 | string | 操作が終了したエラーのクラスを記述します。[2] | DEADLINE_EXCEEDED; java.net.UnknownHostException; -32602 |
rpc.method | | Conditionally Required 利用可能な場合。 | string | RPCインターフェースの観点から見た、完全修飾されたメソッドの論理名。[3] | com.example.ExampleService/exampleMethod; EchoService/Echo; _OTHER |
rpc.response.status_code | | Conditionally Required 利用可能な場合。 | string | RPCサーバーが返した、またはクライアントが生成した、RPCのステータスコード。[4] | OK; DEADLINE_EXCEEDED; -32602 |
server.address | | Conditionally Required 利用可能な場合。 | string | リクエストの送信先であるRPCサーバーインスタンスのグループを識別する文字列。[5] | example.com; 10.1.2.80; /tmp/my.sock |
server.port | | Conditionally Required 適用可能であり、かつ server.address が設定されている場合。 | int | サーバーのポート番号。[6] | 80; 8080; 443 |
[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）。
error.type には、次の既知の値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、そうでない場合は独自の値を使用してもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
_OTHER | 計装が独自の値を定義していない場合に使うフォールバックのエラー値。 | |
rpc.system.name には、次の既知の値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、そうでない場合は独自の値を使用してもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
connectrpc | Connect RPC | |
dubbo | Apache Dubbo | |
grpc | gRPC | |
jsonrpc | JSON-RPC | |