> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/configuration/version-selection/


# セマンティック規約のバージョン選択

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

この文書では、セマンティック規約のバージョン選択のための宣言的設定を定義します。

## 宣言的設定

セマンティック規約のバージョン選択を宣言的設定で行う場合、次のパスの下に置くべきです（SHOULD）。

```
.instrumentation/development.general.<domain>.semconv
```

ここで `<domain>` は次のいずれかです。

- `code`
- `db`
- `gen_ai`
- `http`
- `k8s`
- `messaging`
- `rpc`

次のプロパティをサポートすべきです（SHOULD）。

| Property       | Type    | Required | Default |
| -------------- | ------- | -------- | ------- |
| `version`      | integer | Yes      | (none)  |
| `experimental` | boolean | No       | `false` |
| `dual_emit`    | boolean | No       | `false` |

**`version`**

このドメインの対象とするセマンティック規約バージョン（例: `1`）。

**`experimental`**

`true` の場合、選択したバージョンがプレステーブルか安定版かにかかわらず、その `version` の開発段階の規約を含みます。

**`dual_emit`**

`true` の場合、対象バージョンに加えて1つ前のメジャーバージョンも出力します。
メジャーバージョン間の段階的な移行のためにデュアルエミットを有効にします。

例えば `version=1, dual_emit=true` はv1とv0の両方を出力し、`version=2, dual_emit=true` はv2とv1の両方を出力します。

v0は、最初の安定版セマンティック規約バージョンが定義される前に、個々の計装が出力していた事実上の安定した規約を指します。
これらの規約は計装ごとに異なり、正式に規定されているわけではありませんが、移行の基準として扱われます。

バージョン間で競合が発生した場合、対象（新しい）バージョンを優先すべきです（SHOULD）。
両バージョンの重複しない属性はマージすべきであり（SHOULD）、それによって利用者は以前のバージョンと対象バージョンの両方の属性にアクセスできます。

注: `experimental` フラグは、選択したバージョンにのみ適用され、`dual_emit` によって出力される以前のバージョンには適用されません。

### 未サポートの設定

1つの設定ブロックが、安定性レベルの異なる複数の計装間で共有されることがよくあります。
計装は、未サポートの設定に対して警告を出すべきではなく（SHOULD NOT）、要求された（`version`、`experimental`、`dual_emit`）の3つ組に対して、次の規則を順に適用することで正しくフォールバックすべきです（SHOULD）。

1. **`version`**: 要求されたバージョンがサポートされていない場合、直近でサポートされている前のバージョンにフォールバックします。`experimental` が `false` の場合、安定版サポートのあるバージョンのみが候補になります。
2. **`experimental`**: `true` が要求されたが、解決済みのバージョンに安定版の規約しか存在しない場合、`false` として扱います。
3. **`dual_emit`**: `true` が要求されたが、解決済みのバージョンでデュアルエミットがサポートされていない場合、`false` として扱います。

これらの規則を適用してもサポートされているバージョンが見つからない場合、その計装の既定の振る舞いを使用します。

## 安定版の計装に関する追加規則

安定版の計装は、安定フラグ（`experimental: false`）で動作している際に、既存のテレメトリーを破壊してはなりません（MUST NOT）。
安定性の保証と破壊的変更の定義については、[セマンティック規約の安定性][SemConvStability]を参照してください。

新しい安定版セマンティック規約バージョン（例えばv1）へのサポートを追加する場合、安定版の計装は、[セマンティック規約の安定性][SemConvStability]で定義された安定性の保証にコミットする準備ができるまで、そのバージョンを `experimental: false` の下で公開すべきではありません（SHOULD NOT）。

計装が、安定版セマンティック規約の未安定な実装への早期アクセスをどのように提供するかは、個々の計装に委ねられます。

## `OTEL_SEMCONV_STABILITY_OPT_IN` との関係

計装が宣言的設定と `OTEL_SEMCONV_STABILITY_OPT_IN` 環境変数の両方をサポートする場合、宣言的設定を優先しなければなりません（MUST）。

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
[SemConvStability]: /works/otel-specs-ja/spec/versioning-and-stability/#semantic-conventions-stabilityセマンティック規約の安定性