> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/general/semantic-convention-groups/


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

**ステータス**: [Development][DocumentStatus]

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

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

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

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

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

共通プロパティに加えて、セマンティック規約グループには型固有のプロパティがあります。詳細は[スキーマのドキュメント](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md)を参照してください。

## グループの安定性

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

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

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

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

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

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

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

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

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

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

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

**不安定なグループ:**

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

**安定版グループ:**

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

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

[Stability]: /works/otel-specs-ja/spec/versioning-and-stability/#semantic-conventions-stabilityセマンティック規約の安定性
[MaturityLevel]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.59.0/oteps/0232-maturity-of-otel.md
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status