セマンティック規約グループ

ステータス: Development

スパン、メトリクス、イベント、リソースは、YAMLスキーマのセマンティック規約グループで定義されます。各グループは、次のいずれかになる type プロパティを持ちます。

span - HTTPの CLIENT のような、特定の種類のスパンのセマンティック規約を定義します。
metric - HTTPクライアントリクエストの継続時間のような、特定のメトリクスのセマンティック規約を定義します。
event - 例外のような、特定のイベントのセマンティック規約を定義します。
entity - service のような、テレメトリーが収集される対象となる特定のエンティティのセマンティック規約を定義します。

attribute_group 型を持つグループはセマンティック規約を記述せず、補助的な目的で使われます。

すべてのセマンティック規約グループは、次の共通プロパティを持ちます。

id - 他のスパン、Instrument、イベントと区別して、特定のスパン種別、メトリクスInstrument、イベントを識別します。
brief と note は、その規約の人間が読める説明を提供します。
stability は、その規約の成熟度レベルを記述します。
deprecated プロパティは、その規約を非推奨としてマークし、置き換えやその他の詳細についての情報を提供します。
attributes は、レジストリ内で適用可能な属性への参照を列挙します。

共通プロパティに加えて、セマンティック規約グループには型固有のプロパティがあります。詳細はスキーマのドキュメントを参照してください。

グループの安定性

セマンティック規約グループは、次の安定性レベルを持てます。development、alpha、beta、release_candidate、stable です。

安定性レベルは、attribute_group 型を除くすべての型のグループで必須です。安定性レベルが指定されていない場合、development であると見なされます。

グループの安定性は、stable から他のレベルへ変更してはなりません（MUST NOT）。

任意の安定性レベルのセマンティック規約グループは、レガシーな計装のためのコード生成とドキュメントを保持するために、削除してはなりません（MUST NOT）。

グループの名前が変更されたり、もはや推奨されなくなった場合、そのグループは非推奨にすべきです（SHOULD）。

グループは、その属性の要求レベルが opt_in である場合を除き、グループ自体よりも成熟度レベルが低い属性を参照すべきではありません（SHOULD NOT）。そのような属性参照の要求レベルは、Versioning and Stabilityで許容される場合において、属性がグループの安定性レベルに達した時点で変更してもかまいません（MAY）。例えば、stable のイベントは、opt_in の要求レベルでのみ development の属性を参照できます。その属性が同様に安定版になった時点で、要求レベルを変更してもかまいません。

異なる型のセマンティック規約グループに提供される安定性の保証の詳細については、Versioning and Stabilityを参照してください。

安定性の保証は、テレメトリー項目を記述しないため、attribute_group 型のグループには適用されません。

安定性が混在するグループ

グループに対する安定性の保証は、（type、id、シグナル固有のプロパティなどの）グループのプロパティ、およびこのグループが参照する安定版属性の上書きされたプロパティに適用されます。

グループレベルの安定性の保証は、不安定な属性参照には適用されません。

不安定なグループ:

安定版・不安定版いずれの属性への参照も追加・削除してもかまいません（MAY）。
属性参照の要求レベルやその他のプロパティを変更してもかまいません（MAY）。

安定版グループ:

要求レベルが opt_in である不安定な属性への参照は追加・削除してもかまいません（MAY）。
安定版属性への参照を削除してはなりません（MUST NOT）。

安定版の計装は、デフォルトでセマンティック規約の不安定な部分に従うテレメトリーを報告してはなりません（MUST NOT）。不安定な部分をサポートし、ユーザーがそれをオプトインできるようにしてもかまいません（MAY）。