OpenTelemetryクライアントのバージョニングと安定性

この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/otel/versioning-and-stability/

翻訳元: open-telemetry/opentelemetry-specification v1.60.0（コミット 29ae8c7）

ステータス: Stable

このドキュメントは、OpenTelemetryクライアントが提供する安定性の保証と、それらの保証を満たすためのルールと手順を定義します。

このドキュメントにおいて、「OpenTelemetry」と「言語実装」という用語は、いずれも特にOpenTelemetryクライアントを指します。これらの用語は、このドキュメントにおいて仕様書やCollectorを指すものではありません。

各言語実装は、これらのバージョニングと安定性の要件を踏まえ、これらの要件をどのように満たすかを詳述した言語固有のドキュメントをMUST作成するものとします。このドキュメントは、各リポジトリのルートに配置し、VERSIONINGまたはVERSIONING.mdという名前にしなければなりません（MUST）。

設計目標

バージョニングと安定性の手順は、以下の目標を満たすように設計されています。

アプリケーション所有者がSDKの最新リリースに追従できるようにする。 私たちは、すべてのユーザーがOpenTelemetry SDKの最新バージョンに追従できるようにしたいと考えています。私たちは、ユーザーを古いバージョンに取り残すような、いかなる形のサポートの断絶も生み出したくありません。コンパイルエラーやランタイムエラーを発生させることなく、常にOpenTelemetry SDKの最新のマイナーバージョンへアップグレードできなければなりません（MUST）。

異なるバージョンのOpenTelemetryに依存するパッケージ間で依存関係の衝突を決して生じさせない。安定した公開APIすべての破壊を避ける。 後方互換性は厳格な要件です。計装APIは決してバージョンの衝突を生じさせてはなりません。そうでなければ、OpenTelemetry APIをWebフレームワークのような広く共有されるライブラリに組み込むことができなくなります。APIの古いバージョンに対して書かれたコードは、APIのすべての新しいバージョンでMUST動作するものとします。APIの推移的な依存関係がバージョンの衝突を生じさせることはできません。あるライブラリやアプリケーションが、その依存関係と異なる互換性のないバージョンを必要とする可能性がある場合、OpenTelemetry APIは特定のパッケージに依存することはできません。OpenTelemetry APIをインポートするライブラリが、OpenTelemetryの依存関係のいずれかにおけるバージョンの衝突によって他のライブラリと非互換になることは決してあってはなりません。理論的には、APIを非推奨にし、最終的に削除することは可能ですが、これは年単位で測られるプロセスであり、私たちにはそうする計画はありません。

OpenTelemetryコンポーネントの同一リリース内で、複数レベルのパッケージの安定性を許容する。 保守者に対して、安定したシグナルと並行してDevelopmentステータスの新しいシグナルを開発するための明確なプロセスを提供します。同一リリース内の異なるパッケージは、異なる安定性レベルを持つ場合があります。これは、今日安定したトレーシングをリリースしたい実装は、開発中のメトリクスが、メトリクスAPIへの破壊的変更によってトレースAPIパッケージを不安定化させないような形で切り出されていることをMUST確認するものとする、ということを意味します。

シグナルのライフサイクル

各シグナルの開発は、development、stable、deprecated、removedというライフサイクルに従います。

以下のインフォグラフィックは、APIコンポーネントのライフサイクルの例を示しています。

API Lifecycle

Development

シグナルは、OTEP 0232で定義されるDevelopmentステータスから始まります。シグナルがdevelopment状態にある間、破壊的変更やパフォーマンスの問題が発生する場合があります（MAY）。コンポーネントは機能的に完成していることを期待されるべきではありません（SHOULD NOT）。場合によっては、Development状態のシグナルが完全に破棄され削除されることがあります（MAY）。Development状態のシグナルに対して、長期的な依存関係を持つべきではありません（SHOULD NOT）。

OpenTelemetryクライアントは、既存のシグナルの安定性の保証を破壊することなくDevelopment状態のシグナルを作成できる形でMUST設計されるものとします。

OpenTelemetryクライアントは、シグナルがDevelopmentからStableへ遷移する際に既存のユーザーを破壊する形でMUST NOT設計されるものとします。これは、リリース候補の利用者に不利益を与え、採用を妨げることになります。

「development」のような安定性を示す用語は、ディレクトリ名やインポート名の一部としてMUST NOT使用されるものとします。パッケージのバージョン番号には、異なるステータスのパッケージを区別するために、-alpha、-beta、-rc、-developmentのようなサフィックスが付く場合があります（MAY）。

このリポジトリでは、「Development」ステータスは以前「Experimental」と呼ばれていたことに注意してください。「Experimental」の使用は、すべて「Development」と同様に扱うべきです。

Stable

Development状態にあるシグナルが十分なテストを経ると、Stableへ遷移することがあります（MAY）。このシグナルに対しては、これ以降、長期的な依存関係を持つことができます（MAY）。

シグナルのすべてのコンポーネントが一斉に安定化することもあれば、コンポーネントごとに段階的に安定性へ遷移することもあります（MAY）。APIは、他のコンポーネントよりも先にMUST安定化するものとします。

シグナルのコンポーネントがStableとしてマークされた後は、そのシグナルが存在し続ける限り、以下のルールがMUST適用されるものとします。

API Stability（APIの安定性）

APIパッケージへの後方互換性のない変更は、メジャーバージョン番号が上がらない限りMUST NOT行われるものとします。既存のすべてのAPI呼び出しは、同一メジャーバージョン内のすべての将来のマイナーバージョンに対して、コンパイルと動作をMUST継続するものとします。

バイナリアーティファクトを配布する言語は、APIパッケージについてABI互換性を提供すべきです（SHOULD）。

SDK Stability（SDKの安定性）

SDKパッケージの公開部分は、後方互換性をMUST維持するものとします。公開される機能には2つのカテゴリがあります。プラグインインターフェースとコンストラクタです。プラグインインターフェースとは、SDKの振る舞いをカスタマイズするためにエンドユーザーが実装することを意図した、SDKが提供する拡張点です。プラグインインターフェースの例には、SpanProcessor、Exporter、Samplerがあります。コンストラクタの例には、設定オブジェクト、環境変数、SDKビルダーがあります。

バイナリアーティファクトを配布する言語は、SDKパッケージについてABI互換性を提供すべきです（SHOULD）。

Extending API/SDK abstractions（API/SDKの抽象化の拡張）

既存のAPI/SDKの呼び出しは、対象の言語が後方互換性を保つ形でそれを許容するのであれば、メジャーバージョン番号を上げずに拡張してもかまいません（MAY）。

既存のAPI/SDKの呼び出しに新しいパラメータを追加する方法は、言語によっていくつか考えられます。

既存のメソッドに新しい任意のパラメータを追加する。ABI安定性が保証の一部である言語では、これはABIを破壊する可能性が高いため、適切な方法ではないかもしれません。
新しいパラメータを含む異なるパラメータの組を渡せるメソッドオーバーロードを追加する。これは、メソッドオーバーロードが可能な言語では、おそらく好ましい方法です。

同様に、既存のSDKプラグインインターフェースは、対象の言語がそれを後方互換な形で（例えばデフォルト実装を提供することで）許容するのであれば、メジャーバージョン番号を上げずに新しいメソッドで拡張してもかまいません（MAY）。ここでの後方互換とは、プラグインインターフェースを実装するエンドユーザーのコードが、エンドユーザーのコードに変更を加えることなく新しいバージョンのSDKでも使え続けなければならない（MUST）ということです。Javaのようにバイナリアーティファクトでコードを共有することが一般的な言語では、後方互換とは、プラグインインターフェースを実装するエンドユーザーのコードが、再コンパイルすることなく新しいマイナーバージョンやパッチバージョンでも使え続けなければならない（MUST）ということを意味します。

インターフェースへのこのような後方互換なメソッド追加がある言語で不可能な場合、その言語の保守者は、メジャーバージョンを上げることなく、後方互換な回避策を使ってその追加を実装すべきです（SHOULD）。例えば、可能な回避策の1つは、既存のインターフェースを拡張する代わりに新しいインターフェースを追加し、あらゆる箇所で新旧両方のインターフェースを受け入れることです。

さらに、StableなシグナルのAPI/SDKは、既存のStable APIに新しいメソッドを追加することで拡張してもかまいません（MAY）。言語実装は、以下のようにそれを行う仕組みを持つべきです（SHOULD）。

Development成熟度レベルで新しいメソッドを追加することは可能であり、新しいメソッドを使わないユーザーにとって破壊的変更にはなりません。
Developmentにある新しいメソッドはオプトインを要求すべきです（SHOULD）。これにより、ユーザーは新しいメソッドを使うことに伴うリスクを認識します。追加されたメソッドがDevelopmentであり破壊的変更の対象であることは、ドキュメント化しておくべきです。
Development成熟度レベルにあったがStableへ昇格しなかったメソッドを削除（または非推奨化）することは、そのメソッドを一度も使ったことのないユーザーにとって破壊的変更にはなりません。

既存のAPI/SDKを破壊的でない形で拡張する他の方法もあるでしょう。言語の保守者は、その言語にとってイディオマティックな方法を選ぶべきです（SHOULD）。

Contrib Stability（Contribの安定性）

プラグイン、計装、その他のcontribパッケージは、API、SDK、セマンティック規約の最新バージョンと最新の状態を保ち、互換性を維持すべきです（SHOULD）。API、SDK、セマンティック規約のリリースにcontribパッケージに関連する変更が含まれる場合、そのパッケージは適時に更新およびリリースされるべきです（SHOULD）。（計装の安定性に関する制約についてはTelemetry Stabilityを参照してください。）目標は、ユーザーが依存するプラグインによって足止めされることなく、OpenTelemetryの最新バージョンへ更新できるようにすることです。

contribパッケージの公開部分（コンストラクタ、設定、インターフェース）は、後方互換性を維持すべきです（SHOULD）。

バイナリアーティファクトを配布する言語は、contribパッケージについてABI互換性を提供すべきです（SHOULD）。

例外: contribパッケージは、必須の下流依存関係が安定性を破壊した場合、安定性を破壊してもかまいません（MAY）。例えば、データベース統合は、必要なデータベースクライアントが安定性を破壊した場合、安定性を破壊することがあります。しかし、古いcontribパッケージは安定を保つことが強く推奨されます（RECOMMENDED）。統合の新しい非互換バージョンは、既存のcontribパッケージを破壊するのではなく、別のcontribパッケージとしてリリースされるべきです（SHOULD）。

Semantic Conventions Stability（セマンティック規約の安定性）

[!WARNING] テレメトリーの安定性のためにスキーマ変換に依拠することについては、現在モラトリアム（一時停止）が設けられています。

セマンティック規約は、計装が提供するシグナルと、その計装を消費する分析ツール（ダッシュボード、アラート、クエリなど）との間の契約を定義します。

OpenTelemetryの計装が生成するテレメトリーへの変更は、ダッシュボードやアラートといった分析ツールを破壊することを避けるべきです（SHOULD）。これを実現しつつテレメトリーとセマンティック規約の進化を許容するため、OpenTelemetryはテレメトリースキーマという概念に依拠しています。

セマンティック規約は、破壊的変更を、それが生成するテレメトリーに対して書かれたツールの一般的な使用方法を破壊するような変更として定義します。つまり、専用のツール（アラート、ダッシュボードなど）が関与するテレメトリーの部分は、スキーマ変換が適用された後、そのツールに対して安定であることが期待されます。これらは、デフォルト設定においてユーザーによる介入（Sampler、Viewなど）がないことも前提としています。

セマンティック規約は、OTLPデータモデルにおける以下のフィールド群を定義します。

Resource
- 属性キー（属性のキーと値のペアのキー部分）
- Entity References
  - エンティティタイプ
  - 識別子（リソースの属性キーの保証を継承する）
InstrumentationScope
- 属性キー
  - トレーサーの取得時に提供されるもの
  - メーターの取得時に提供されるもの
- 既知の値のリストで定義されている属性値
Trace
- span上の以下のデータ
  - スパン名
  - スパン種別
  - スパンに提供された属性キー
    - サンプリングに関する事情により、これらの属性がスパン開始時に提供されなければならないかどうか
  - スパンに提供された属性値のうち、既知の値のリストで定義されているもの
- span eventで提供される以下のデータ
  - イベント名
  - イベントに提供された属性キー
  - イベントに提供された属性値のうち、既知の値のリストで定義されているもの
Metrics
- Metricの以下の部分（Instrumentの構築時に渡される）
  - メトリクスの名前（デフォルトはInstrumentの名前）
  - メトリクスデータの種別（Gauge、Sum、Histogram、ExponentialHistogram）
    - CounterとUpDownCounterのInstrumentについては、メトリック種別を保つ限り、非同期と同期のInstrument間で変更することは許容されます。
  - メトリクスの単位（デフォルトはInstrumentの単位）
- 各*DataPoint上の属性キー
  - これらは、同期・非同期の両方のInstrumentについて、測定値を記録する際にAPIで提供されます。
  - これらはNumberDataPoint、HistogramDataPoint、ExponentialHistogramDataPoint、SummaryDataPointに存在します。
- 各*DataPoint上の属性値のうち、既知の値のリストで定義されているもの
Log Records
- LogRecordに提供された属性キー
- LogRecordに提供された属性値のうち、既知の値のリストで定義されているもの
- イベント名

上記に列挙されていないものは、セマンティック規約によって安定であることが期待されておらず、変更が許容されている（あるいは想定されている）ものです。いくつか例を示します。

属性の値
- 例外は、既知の値のリストに存在する既存の値です。ただし、こうしたリストに新しい値を追加することはできます。コンシューマーは未知の値が来ることを想定しておくべきです。
スパンに付与されたリンク
メトリクスの記録される測定値の型（floatまたはinteger）は強制されておらず、変更が許容されています。
メトリックInstrumentの説明。
Instrumentによって記録される値。

安定性の保証が及ぶテレメトリーフィールドのリストは、拡張されることがあります（MAY）。

この仕様書におけるセマンティック規約への変更は、その変更がスキーマファイルによって記述できる限り許容されます。現時点で記述・許容されている変更は以下です。

スパン、メトリクス、ログ、リソースの属性の名称変更。
メトリクスの名称変更。
スパンイベントの名称変更。

このようなすべての変更は、OpenTelemetryのスキーマファイル形式で記述し、このリポジトリで公開しなければなりません（MUST）。詳細はOpenTelemetryのスキーマがどのように公開されるかを参照してください。

計装がスキーマを使って生成する計装内容をどのように変更できるかについては、Telemetry Stabilityドキュメントを参照してください。

例外: 一部のリソース属性は、仕様書の様々な場所に埋め込まれています。例えば、SDKが生成することを要求されるservice.*属性は、汎用SDK設定で定義された対応する環境変数を持っています。これらのリソース属性は決して変更されてはなりません（MUST NOT）。これらは、この仕様書のハードコードされた一部とみなされます。

上記の3種類の変更に加えて、常に許容される種類の変更もあります。このような変更は、スキーマファイルによって記述する必要はなく（また記述されません）。そうした変更の一覧は以下です。

リソース、スパン、スパンイベント、ログレコードの既存のセマンティック規約に新しい属性を追加すること。
アラートのしきい値の変更が必要になるような形で既存のタイムシリーズを「分解」しない範囲で、既存のメトリクスに新しい属性を追加すること。
新しい種類のリソース、スパン、スパンイベント、メトリクス、ログレコードに対するセマンティック規約を追加すること。

セマンティック規約へのその他の変更は現時点では禁止されています。他の種類の変更は、この仕様書の将来のバージョンで導入されることがあります（MAY）。これは、OpenTelemetryがそうした変更を記述できる新しいスキーマファイル形式を導入した場合にのみ許容されます。

Telemetry Stability（テレメトリーの安定性）

計装が生成するテレメトリーの安定性については、Telemetry Stabilityドキュメントを参照してください。

Deprecated

シグナルは、最終的に置き換えられることがあります（MAY）。これが起きると、deprecatedとしてマークされます。

シグナルは、置き換え先がstableでない限りdeprecatedとしてマークされてはなりません（MUST NOT）。Deprecatedなコードは、stableなコードと同じサポートの保証にMUST従うものとします。

Removed

サポートは、リリースからシグナルが削除されることで終了します。これが起きるとき、そのリリースはMUSTメジャーバージョンを上げるものとします。

シグナルの置き換えについての注記

現在、v1.0を超えるOpenTelemetryのメジャーバージョンを作成する計画はないことに注意してください。

明確にしておくと、実際にv2.0へ移行してサポートを打ち切ることなく、既存のシグナルの新しい後方互換性のないバージョンを作成することは依然として可能です。

例えば、新しくより優れたトレーシングAPIを開発し、それをAwesomeTraceと呼ぶことにしたとしましょう。私たちは、現在のトレーシングAPIをAwesomeTraceへ変化させることは決してしません。代わりに、AwesomeTraceは、現在のトレーシングシグナルと共存し相互運用する、まったく新しいシグナルとして追加されます。これにより、AwesomeTraceの追加はマイナーバージョンの増加となり、v2.0にはなりません。v2.0は、現在のトレーシングのサポート終了を意味し、AwesomeTraceの追加を意味するものではありません。そして、可能な限り、私たちはそのサポートを終了したくありません。

これは実際、理論上の例ではありません。OpenTelemetryは既に2つのトレーシングAPI、OpenTelemetryとOpenTracingをサポートしています。私たちは新しいトレーシングAPIを発明しましたが、古いものへのサポートも継続しています。

バージョン番号

OpenTelemetryクライアントは、以下の明確化を伴いSemantic Versioning 2.0.0にMUST従うものとします。

OpenTelemetryクライアントには、API、SDK、セマンティック規約、Contribという4つのコンポーネントがあります。

バージョニングの目的においては、あるコンポーネント内のすべてのコードは単一のパッケージの一部であるかのようにMUST扱われ、同じバージョン番号でバージョン付けされるものとします。ただし、複数のパッケージの集合として個別にバージョン付けされうるContribは例外です。

すべての安定したAPIパッケージは、すべてのシグナルにわたってMUST一緒にバージョン付けされるものとします。Stableなシグナルは個別のバージョン番号をMUST NOT持つものとします。特定のバージョン番号でラベル付けされたAPIリリースに含まれるすべてのシグナルに適用される、単一のバージョン番号が存在します。
すべてのシグナルのSDKパッケージは、すべてのシグナルにわたってMUST一緒にバージョン付けされるものとします。シグナルは個別のバージョン番号をMUST NOT持つものとします。特定のバージョン番号でラベル付けされたSDKリリースに含まれるすべてのシグナルに適用される、単一のバージョン番号が存在します。
セマンティック規約は、単一のバージョン番号を持つ単一のパッケージです。
各contribパッケージは、それぞれ独自のバージョン番号を持つことがあります（MAY）。
API、SDK、セマンティック規約、contribの各コンポーネントは、独立したバージョン番号を持ちます。例えば、opentelemetry-python-apiの最新バージョンがv1.2.3である一方、opentelemetry-python-sdkの最新バージョンがv2.3.1であってもかまいません（MAY）。
異なる言語実装は、独立したバージョン番号を持ちます。例えば、opentelemetry-java-apiがv1.3.2であるときにopentelemetry-python-apiがv1.2.8であっても問題ありません。
言語実装は、それが実装する仕様書とは独立したバージョン番号を持ちます。例えば、opentelemetry-python-apiのv1.8.2が仕様書のv1.1.1を実装していても問題ありません。

例外: 一部の言語では、パッケージマネージャーが0.Xより高いバージョンを持つ不安定なパッケージにうまく対応できないことがあります。このような場合、Development状態のシグナルは、0.Xのバージョン番号を保つために、stableなシグナルとは独立してバージョン付けされることがあります（MAY）。シグナルがstableになったときは、そのバージョンはリリース内の他のstableなシグナルに合わせてMUST上げられるものとします。

メジャーバージョンの増加

メジャーバージョンの増加は、stableなインターフェースへの破壊的変更が生じた場合、またはdeprecatedなシグナルが削除された場合にMUST発生するものとします。メジャーバージョンの増加は、何らかの形のサポートの喪失を伴わない変更ではSHOULD NOT発生しないものとします。

マイナーバージョンの増加

OpenTelemetryクライアントへのほとんどの変更は、マイナーバージョンの増加をもたらします。

いずれかのコンポーネントに追加された、新しい後方互換な機能。
内部のSDKコンポーネントへの破壊的変更。
development状態のシグナルへの破壊的変更。
Development状態の新しいシグナルの追加。
Development状態のシグナルがstableになること。
Stableなシグナルがdeprecatedになること。

パッチバージョンの増加

パッチバージョンは、再コンパイルを要求したり、アプリケーションコードを破壊する可能性のある変更を含みません。以下は、パッチ修正の例です。

上記のルールに従いマイナーバージョンの増加を要求しないバグ修正。
セキュリティ修正。
ドキュメント。

現在、OpenTelemetryプロジェクトには、SDKの以前のマイナーバージョンへバグ修正やセキュリティ修正をバックポートする計画はありません。セキュリティ修正とバグ修正は、最新のマイナーバージョンにのみ適用されることがあります（MAY）。私たちは、エンドユーザーがOpenTelemetry SDKの最新バージョンに追従し続けられるようにすることに力を入れています。

言語バージョンサポート

各言語実装は、サポート対象の言語やランタイムのバージョンの削除がそのバージョニングにどう影響するかを定義すべきです（SHOULD）。原則として、対象のエコシステムにおける慣習に従うべきです（SHOULD）。

長期サポート

long term support

API support（APIサポート）

APIのメジャーバージョンは、次のメジャーAPIバージョンのリリース後、最低3年間サポートがMUST維持されるものとします。APIサポートは以下のように定義されます。

上記で定義されるAPIの安定性は、MUST維持されるものとします。
APIの直前のメジャーバージョンの最新のマイナーバージョンをサポートするSDKのバージョンは、長期サポート期間中も引き続き保守されます。バグ修正とセキュリティ修正はMUSTバックポートされるものとします。追加の機能開発は推奨されません（NOT RECOMMENDED）。
APIがバージョン付けされた時点で利用可能だったcontribパッケージは、長期サポートの期間中、継続してMUST保守されるものとします。バグ修正とセキュリティ修正はバックポートされます。追加の機能開発は推奨されません（NOT RECOMMENDED）。

SDK Support（SDKサポート）

上記で定義されるSDKの安定性は、次のメジャーSDKバージョンのリリース後、最低1年間維持されます。

Contrib Support（Contribサポート）

上記で定義されるContribの安定性は、contribパッケージの次のメジャーバージョンのリリース後、最低1年間維持されます。

OpenTelemetry GA

「OpenTelemetry GA」という用語は、OpenTracingとOpenCensusが完全にdeprecatedとなる時点を指します。GAを宣言するための最低要件は以下のとおりです。

トレーシングとメトリクスの両方のstableなバージョンが、少なくとも4つの言語でMUSTリリースされるものとします。
これらの言語に対して、CI/CD、パフォーマンス、統合テストがMUST実装されるものとします。