Yoshi Yamaguchi

この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/semconv/rpc/grpc/

翻訳元: open-telemetry/semantic-conventions v1.44.0（コミット e10a930）

gRPCに関するセマンティック規約

ステータス: Release Candidate（特に断りがない限り）

gRPCに関するセマンティック規約は、RPCセマンティック規約を拡張・上書きします。

[!NOTE] gRPCプロジェクトは、メトリクスとスパンについて独自の規約を定義しています。

このリポジトリで定義されているOpenTelemetryのスパンとメトリクスが、gRPCネイティブの規約とどのように関連しているかの詳細は、gRPCとの互換性の文書に記載されています。

Spans

Client

Status: Release Candidate

このスパンは、送信されるリモートプロシージャコール（RPC）を表します。

rpc.system.name は "grpc" に設定しなければならず（MUST）、スパン作成時点で提供されるべきです（SHOULD）。

Span name: 名前の節を参照してください。

Span kind は CLIENT でなければなりません（MUST）。

Span status: スパンステータスの記録方法の詳細については、エラーの記録を参照してください。どの値がエラーに分類されるかの詳細は rpc.response.status_code 属性も参照してください。

Attributes:

KeyStabilityRequirement LevelValue TypeDescriptionExample Values
rpc.methodRelease CandidateRequiredstringRPCインターフェースの観点から見た、完全修飾されたメソッドの論理名。[1]com.example.ExampleService/exampleMethod; EchoService/Echo; _OTHER
rpc.response.status_codeRelease CandidateRequiredstringサーバーが返した、またはクライアントが生成したステータスコードの文字列表現。[2]OK; DEADLINE_EXCEEDED; -32602
server.addressStableRequiredstringリクエストの送信先であるRPCサーバーインスタンスのグループを識別する文字列。[3]example.com; 10.1.2.80; /tmp/my.sock
error.typeStableConditionally Required 操作が失敗した場合に限る。string操作が終了したエラーのクラスを記述します。[4]DEADLINE_EXCEEDED; java.net.UnknownHostException; -32602
rpc.method_originalRelease CandidateConditionally Required rpc.method と異なる場合に限る。stringクライアントが使用した元のメソッド名。com.myservice.EchoService/catchAll; com.myservice.EchoService/unknownMethod; InvalidMethod
server.portStableConditionally Required [5]intサーバーのポート番号。[6]50051
network.peer.addressStableRecommendedstringネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。[7]10.1.2.80; /tmp/my.sock
network.peer.portStableRecommended network.peer.address が設定されている場合。intネットワーク接続のピアポート番号。65123
rpc.request.metadata.<key>DevelopmentOpt-Instring[]RPCリクエストのメタデータ。<key> は正規化されたRPCメタデータキー（小文字）で、値はそのメタデータの値。[8]["1.2.3.4", "1.2.3.5"]
rpc.response.metadata.<key>DevelopmentOpt-Instring[]RPCレスポンスのメタデータ。<key> は正規化されたRPCメタデータキー（小文字）で、値はそのメタデータの値。[9]["attribute_value"]

[1] rpc.method: メソッド名は、エッジケースやエラーケースにおいて無制限のカーディナリティを持つことがあります（MAY）。

一部のRPCフレームワークやライブラリは、クライアントスタブとサーバー実装に対して、既知のメソッドの固定集合を提供します。そのようなフレームワーク向けの計装は、メソッドがフレームワークやライブラリによって認識されている場合に限り、この属性を元のメソッド名に設定しなければなりません（MUST）。

メソッドが認識されない場合、例えばサーバーがサーバー上で事前定義されていないメソッドへのリクエストを受信した場合や、計装がメソッドが事前定義されているかどうかを確実に検出できない場合、この属性は _OTHER に設定しなければなりません（MUST）。

RPC計装が有効なRPCメソッドを _OTHER に変換してしまう可能性がある場合、既知のRPCメソッドの一覧を設定する方法を提供すべきです（SHOULD）。

rpc.method は、実装しているメソッド・関数の名前とは異なることがあります。 code.function.name 属性は、サーバー側で実際に呼び出しを実行している完全修飾メソッド、またはクライアント側のRPCクライアントスタブメソッドを記録するために使用できます。

[2] rpc.response.status_code: OK 以外のすべてのステータスコードはエラーとみなすべきです（SHOULD）。

[3] server.address: 計装は、gRPCチャネルの作成時に使用された設定に基づいて server.address（および server.port）を設定すべきで（SHOULD）、低カーディナリティを保証するために実際のネットワークレベルの接続情報をこの目的で使用すべきではありません（SHOULD NOT）。

計装は、使用されているスキームに応じて、gRPCの名前解決仕様に従ってgRPCのターゲット文字列からアドレスとポートを解析してもかまいません（MAY）。あるいは、この情報を提供するgRPCクライアントAPIを使用してもかまいません（MAY）。

計装が、サーバーのドメイン名や、サーバーインスタンスのグループに対する他の適切な低カーディナリティの識別子をターゲット文字列から決定できない場合、server.address をターゲット文字列全体に設定すべきで（SHOULD）、server.port は設定すべきではありません（SHOULD NOT）。

アドレスがIPアドレスである場合、計装は逆引きDNSルックアップを行ってDNS名を得るべきではなく（SHOULD NOT）、提供されたIPアドレスを server.address に設定すべきです（SHOULD）。

例:

  • ターゲット文字列 grpc.io:50051 が与えられた場合、想定される属性は次のとおりです。
    • server.address: "grpc.io"
    • server.port: 50051
  • ターゲット文字列 dns://1.2.3.4/grpc.io:50051 が与えられた場合、想定される属性は次のとおりです。
    • server.address: "grpc.io"
    • server.port: 50051
  • ターゲット文字列 unix:///run/containerd/containerd.sock が与えられた場合、想定される属性は次のとおりです。
    • server.address: "/run/containerd/containerd.sock"
    • server.port: 設定なし
  • ターゲット文字列 zk://zookeeper:2181/my-server が与えられた場合、想定される属性は次のとおりです。
    • server.address: "zk://zookeeper:2181/my-server"
    • server.port: 設定なし
  • ターゲット文字列 ipv4:198.51.100.123:50051,198.51.100.124:50051 が与えられた場合、想定される属性は次のとおりです。
    • server.address: "ipv4:198.51.100.123:50051,198.51.100.124:50051"
    • server.port: 設定なし

[4] error.type: ステータスコードが返される前にRPCがエラーで失敗した場合、error.type は例外の型（該当する場合は完全修飾クラス名）またはコンポーネント固有の低カーディナリティなエラー識別子に設定すべきです（SHOULD）。

レスポンスのステータスコードが返され、そのステータスがエラーを示している場合、error.type はそのステータスコードに設定すべきです（SHOULD）。rpc.response.status_code のどの値がエラーとみなされるかの詳細は、システム固有の規約を確認してください。

error.type の値は予測可能であるべきで（SHOULD）、低カーディナリティであるべきです（SHOULD）。計装は報告するエラーの一覧を文書化すべきです（SHOULD）。

リクエストが正常に完了した場合、計装は error.type を設定すべきではありません（SHOULD NOT）。

[5] server.port: ポートが利用可能で、かつ server.address が設定されている場合に限る。

[6] server.port: ターゲット文字列の解析方法の詳細は server.address を参照してください。

[7] network.peer.address: RPCが複数のネットワーク呼び出しを含む場合（例えば再試行）、最後に接続したアドレスを使用すべきです（SHOULD）。

[8] rpc.request.metadata.<key>: 計装は、どのメタデータの値を取得するかを明示的に設定できるようにすべきです（SHOULD）。 すべてのリクエストメタデータの値を含めることはセキュリティ上のリスクとなり得ます。明示的な設定によって機密情報の漏洩を避けやすくなります。

例えば、値が ["1.2.3.4", "1.2.3.5"] であるプロパティ my-custom-key は、値 ["1.2.3.4", "1.2.3.5"] を持つ rpc.request.metadata.my-custom-key 属性として記録されるべきです（SHOULD）。

[9] rpc.response.metadata.<key>: 計装は、どのメタデータの値を取得するかを明示的に設定できるようにすべきです（SHOULD）。 すべてのレスポンスメタデータの値を含めることはセキュリティ上のリスクとなり得ます。明示的な設定によって機密情報の漏洩を避けやすくなります。

例えば、値が ["attribute_value"] であるプロパティ my-custom-key は、値 ["attribute_value"] を持つ rpc.response.metadata.my-custom-key 属性として記録されるべきです（SHOULD）。

次の属性は、サンプリングの判断を行う上で重要になる場合があり、（何であれ提供する場合には）スパン作成時点で提供されるべきです（SHOULD）。

error.type には、次の既知の値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、そうでない場合は独自の値を使用してもかまいません（MAY）。

ValueDescriptionStability
_OTHER計装が独自の値を定義していない場合に使うフォールバックのエラー値。Stable

Server

Status: Release Candidate

このスパンは、受信するリモートプロシージャコール（RPC）を表します。

rpc.system.name は "grpc" に設定しなければならず（MUST）、スパン作成時点で提供されるべきです（SHOULD）。

Span name: 名前の節を参照してください。

Span kind は SERVER でなければなりません（MUST）。

Span status: スパンステータスの記録方法の詳細については、エラーの記録を参照してください。どの値がエラーに分類されるかの詳細は rpc.response.status_code 属性も参照してください。

Attributes:

KeyStabilityRequirement LevelValue TypeDescriptionExample Values
rpc.response.status_codeRelease CandidateRequiredstringサーバーが返したステータスコードの文字列表現。[1]OK; DEADLINE_EXCEEDED; -32602
error.typeStableConditionally Required 操作が失敗した場合に限る。string操作が終了したエラーのクラスを記述します。[2]DEADLINE_EXCEEDED; java.net.UnknownHostException; -32602
rpc.methodRelease CandidateConditionally Required 利用可能な場合。stringRPCインターフェースの観点から見た、完全修飾されたメソッドの論理名。[3]com.example.ExampleService/exampleMethod; EchoService/Echo; _OTHER
rpc.method_originalRelease CandidateConditionally Required rpc.method と異なる場合に限る。stringクライアントが使用した元のメソッド名。com.myservice.EchoService/catchAll; com.myservice.EchoService/unknownMethod; InvalidMethod
server.addressStableConditionally Required 利用可能な場合。stringリクエストの送信先であるRPCサーバーインスタンスのグループを識別する文字列。[4]example.com; 10.1.2.80; /tmp/my.sock
server.portStableConditionally Required 適用可能であり、かつ server.address が設定されている場合。intサーバーのポート番号。[5]80; 8080; 443
network.peer.addressStableRecommendedstringネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。[6]10.1.2.80; /tmp/my.sock
network.peer.portStableRecommended network.peer.address が設定されている場合。intネットワーク接続のピアポート番号。65123
rpc.request.metadata.<key>DevelopmentOpt-Instring[]RPCリクエストのメタデータ。<key> は正規化されたRPCメタデータキー（小文字）で、値はそのメタデータの値。[7]["1.2.3.4", "1.2.3.5"]
rpc.response.metadata.<key>DevelopmentOpt-Instring[]RPCレスポンスのメタデータ。<key> は正規化されたRPCメタデータキー（小文字）で、値はそのメタデータの値。[8]["attribute_value"]

[1] rpc.response.status_code: 次のステータスコードはエラーとみなすべきです（SHOULD）。

  • UNKNOWN
  • DEADLINE_EXCEEDED
  • UNIMPLEMENTED
  • INTERNAL
  • UNAVAILABLE
  • DATA_LOSS

[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] server.address: DNS名、サービスレジストリ内のエンドポイントとパス、ローカルソケット名、またはIPアドレスを含む場合があります。 個々のRPCシステムに関するセマンティック規約は、この属性への値の設定方法を文書化すべきです（SHOULD）。 アドレスがIPアドレスである場合、計装はDNS名を得るための逆引きDNSルックアップを行うべきではなく（SHOULD NOT）、server.address を提供されたIPアドレスに設定すべきです（SHOULD）。

[5] server.port: クライアント側から観測され、かつ中間装置を介して通信している場合、server.port は利用可能であれば、プロキシなどの中間装置の背後にあるサーバーのポートを表すべきです（SHOULD）。

[6] network.peer.address: RPCが複数のネットワーク呼び出しを含む場合（例えば再試行）、最後に接続したアドレスを使用すべきです（SHOULD）。

[7] rpc.request.metadata.<key>: 計装は、どのメタデータの値を取得するかを明示的に設定できるようにすべきです（SHOULD）。 すべてのリクエストメタデータの値を含めることはセキュリティ上のリスクとなり得ます。明示的な設定によって機密情報の漏洩を避けやすくなります。

例えば、値が ["1.2.3.4", "1.2.3.5"] であるプロパティ my-custom-key は、値 ["1.2.3.4", "1.2.3.5"] を持つ rpc.request.metadata.my-custom-key 属性として記録されるべきです（SHOULD）。

[8] rpc.response.metadata.<key>: 計装は、どのメタデータの値を取得するかを明示的に設定できるようにすべきです（SHOULD）。 すべてのレスポンスメタデータの値を含めることはセキュリティ上のリスクとなり得ます。明示的な設定によって機密情報の漏洩を避けやすくなります。

例えば、値が ["attribute_value"] であるプロパティ my-custom-key は、値 ["attribute_value"] を持つ rpc.response.metadata.my-custom-key 属性として記録されるべきです（SHOULD）。

次の属性は、サンプリングの判断を行う上で重要になる場合があり、（何であれ提供する場合には）スパン作成時点で提供されるべきです（SHOULD）。

error.type には、次の既知の値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、そうでない場合は独自の値を使用してもかまいません（MAY）。

ValueDescriptionStability
_OTHER計装が独自の値を定義していない場合に使うフォールバックのエラー値。Stable

Metrics

gRPCの計装は、RPCメトリクスに関するセマンティック規約の全般的な規約に従ってメトリクスを収集すべきです（SHOULD）。

rpc.system.name は "grpc" に設定しなければなりません（MUST）。