属性の要求レベル

ステータス: Stable

この節は、ログ、メトリクス、リソース、スパンに適用され、セマンティック規約で定義される属性の要求レベルについて説明します。

属性の要求レベルは、計装ライブラリに適用されます。

属性の要求レベルは、計装対象のエンティティ間での属性の可用性、パフォーマンス、セキュリティ、その他の要因に応じて、セマンティック規約によって指定されます。要求レベルを指定する際、セマンティック規約はシグナル固有の要件を考慮しなければなりません（MUST）。

例えば、高いカーディナリティを持つ可能性があるメトリクス属性は、Opt-In レベルでのみ定義できます。

別のセマンティック規約の属性を参照するセマンティック規約は、自身のスコープ内でその要求レベルを変更してもかまいません（MAY）。それ以外の場合は、参照元のセマンティック規約の要求レベルが適用されます。

例えば、Database semantic convention は、General attributes で定義されている network.transport 属性を参照し、Conditionally Required レベルを設定しています。

要求レベル

以下の表は、テレメトリーシグナル上での属性のデフォルトの包含挙動と、それを設定オプションで変更できるかどうかを示しています。

レベル	デフォルトで含まれる	設定による包含が可能	設定による除外が可能
Required	Yes	n/a	No
Conditionally Required	Yes [1]	No [1]	No [1]
Recommended	Yes [2]	No [2]	Yes
Opt-In	No	Yes	Yes

[1]: 属性の要求条件や指示が満たされていない場合を除きます。

[2]: Recommended の節で説明されている理由により除外された場合を除きます。

Required

すべての計装は、その属性を設定しなければなりません（MUST）。Required属性を定義するセマンティック規約は、計装ライブラリとアプリケーションの絶対多数がそれを効率的に取得・設定でき、かつその規約が定義するシグナルに固有のカーディナリティ、セキュリティなどの要件も満たせることを期待しています。http.request.method はRequired属性の一例です。

注: テレメトリーの利用者は、そのテレメトリー項目が特定のセマンティック規約に従っているかどうかを、その規約で定義されているRequired属性の有無を確認することで検出できます。例えば、スパン上に db.system.name 属性が存在することは、そのスパンがデータベースのセマンティクスに従っていることの指標として使えます。

Conditionally Required

指定された条件が満たされる場合、すべての計装はその属性を設定しなければなりません（MUST）。Conditionally Required属性のセマンティック規約は、その属性を設定すべき条件を明確にしなければなりません（MUST）。

http.route は、計装対象のHTTPフレームワークが、計装対象のリクエストに関するルート情報を提供する場合に設定される、Conditionally Required属性の一例です。一部の低レベルなHTTPサーバー実装はルーティングをサポートしておらず、対応する計装はこの属性を設定できません。

Conditionally Required属性の条件が満たされておらず、その属性を設定する要件がない場合、セマンティック規約はその扱い方について特別な指示を提供してもかまいません（MAY）。指示が与えられておらず、かつ計装がその属性を設定できる場合、計装はその属性にOpt-Inの要求レベルを使うべきです（SHOULD）。

例えば、server.address は規約によってConditionally Requiredとされています。サーバーのIPアドレスの代わりが利用可能な場合、計装はDNSルックアップを行い、キャッシュして server.address を設定できますが、これはDNSルックアップが引き起こすパフォーマンス上の問題を考慮して、ユーザーが明示的に計装を有効化した場合に限ります。

パフォーマンス、セキュリティ、プライバシー、その他の考慮事項により、デフォルトで Recommended 属性を設定しないことを選ぶ計装は、それらの属性が論理的に適用可能であれば、Opt-Inの要求レベルで定義されているとおりにユーザーがそれらを発行するようオプトインできるようにすべきです（SHOULD）。

Opt-In

計装は、ユーザーが計装をそのように設定した場合に限り、その属性を設定すべきです（SHOULD）。設定をサポートしていない計装は、Opt-In 属性を設定してはなりません（MUST NOT）。

この属性要求レベルは、取得コストが特に高い属性や、セキュリティ・プライバシー上のリスクをもたらす可能性がある属性に推奨されます。したがって、これらはユーザーが十分な情報に基づいて明示的に有効化した場合にのみ有効にすべきです。

パフォーマンスに関する提案

デフォルトでは避けるべき、コストの高い操作の例をいくつか挙げます。

計装がIPアドレスしか利用できない場合に server.address を設定するためのDNSルックアップ。ルックアップ結果をキャッシュしても、あらゆるケースでこの問題が解決するわけではなく、デフォルトでは避けるべきです。
HTTPフレームワークが http.route を計算する前に、その計算を強制すること。
Content-Length ヘッダーが利用できない場合に、http.response.body.size を求めるためにレスポンスストリームを読み取ること。