Yoshi Yamaguchi

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

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

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

ステータス: Development

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

宣言的設定

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

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

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

  • code
  • db
  • gen_ai
  • http
  • k8s
  • messaging
  • rpc

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

PropertyTypeRequiredDefault
versionintegerYes(none)
experimentalbooleanNofalse
dual_emitbooleanNofalse

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）。 安定性の保証と破壊的変更の定義については、セマンティック規約の安定性を参照してください。

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

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

OTEL_SEMCONV_STABILITY_OPT_IN との関係

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