OTEP-0232: OpenTelemetryのSIGが統一的に使用する成熟度レベルの定義

2023年3月8日、OpenTelemetryのGCとTCはOpenTelemetryリーダーシップサミットを開催し、さまざまなトピックについて議論しました。そこで議論されたテーマの一つが、OpenTelemetryプロジェクトの成熟度を記述するための標準的なルールの確立でした。本OTEPはそこで議論された内容をまとめたものであり、より広いコミュニティからのフィードバックを得ることを意図しています。

本OTEPは、これまでにプロジェクトが伝えてきた内容、特にOpenTelemetryクライアントのバージョニングと安定性を土台にしています。

Collectorの安定性レベルが、この成熟度レベルの着想元になっています。

動機

コミュニティはしばしば、その多様なコンポーネント群の品質と成熟度に対する期待について問われます。本OTEPは、プロジェクトの名の下にあるSIGの成果物やコンポーネントの成熟度を伝えるためのフレームワークを確立することで、この点を明確にすることを目指しています。 OpenTelemetryプロジェクトは多数のSIGから構成されており、各SIGはさまざまな品質のコンポーネントを複数持っているため、このフレームワークを持つことは、統一された呼称を用いてOpenTelemetryのユーザーに対して適切な期待値を設定する助けとなります。

解説

成熟度レベル

SIGの成果物には、SIGのメンテナー（SIGs）によって、おそらくコードオーナーの意見を取り入れながら確立された成熟度レベルが宣言されていなければなりません（MUST）。主要な成果物には特定の成熟度レベルが設定される一方で、個々のコンポーネントには異なる成熟度レベルが設定される場合があります。例:

Collectorのコアディストリビューションはそれ自体を安定していると宣言しつつ、安定していないレシーバーを含んでいるかもしれません。その場合、そのレシーバーはそのように明確にマークされなければなりません
Javaエージェントは安定していると宣言される一方で、個々の計装パッケージはそうではないかもしれません

コンポーネントは、そのユーザーに見えるインターフェースが安定していない場合、安定していると表示されるべきではありません（SHOULD NOT）。たとえば、Collectorのコンポーネントotlpreceiverが、成熟度レベル「beta」とマークされたOpenTelemetry Collector APIの「config」パッケージへの依存を宣言している場合、otlpreceiverはせいぜい「beta」であるべきです。メンテナーは、ユーザーが将来の変更の影響を受けないと考えるのであれば、この推奨事項から自由に逸脱できます。

本ドキュメントの目的においては、破壊的変更とは、私たちのコンポーネントの利用者が、コンポーネントの利用における混乱を避けるために自ら適応する必要が生じるような変更として定義されます。

Development

コンポーネントの部品のすべてがまだ揃っているわけではなく、ユーザーにまだ提供されていない可能性があります。バグやパフォーマンスの問題が報告されることが見込まれます。設定オプション、コンポーネントのオブザーバビリティ、技術的な実装の詳細、コンポーネントの計画中のユースケースなど、コンポーネントのUXに関するユーザーからのフィードバックが望まれます。設定オプションは、物事がどのように進展するかによって、頻繁に変更される可能性があります。コンポーネントは本番環境で使用されるべきではありません（SHOULD NOT）。コンポーネントは事前通知なしに削除される場合があります（MAY）。

Alpha

これはデフォルトのレベルです。明示的な成熟度レベルが指定されていないコンポーネントはすべて「Alpha」であると見なされるべきです。コンポーネントは限定的で重要度の低い本番ワークロードで使用できる状態にあり、このコンポーネントの作者はユーザーからのフィードバックを歓迎します。バグやパフォーマンスの問題は報告することが推奨されますが、コンポーネントのオーナーがすぐにそれに取り組むとは限りません。コンポーネントのインターフェースや設定オプションは、後方互換性の保証なしに頻繁に変更される可能性があります。この段階のコンポーネントは、通知なしにいつでも廃止される可能性があります。

Beta

Alphaと同様ですが、インターフェース（API、設定、生成されるテレメトリー）は可能な限り安定していると扱われます。リリース間で破壊的変更が生じる可能性はありますが、コンポーネントのオーナーはそれを最小限に抑えるよう努めるべきです。この段階のコンポーネントは、そのAlphaフェーズの間にすでに重要度の低い本番ワークロードへの露出を経験していることが見込まれ、それによってより広い用途に適したものとなります。

Release Candidate

コンポーネントは機能的に完成しており、より広い用途に使用できる準備ができています。コンポーネントは安定していると宣言される準備ができていますが、それが実現する前に、より多くの本番環境でテストされる必要があるかもしれません。バグやパフォーマンスの問題が報告されることが見込まれ、コンポーネントのオーナーがそれに取り組むという期待があります。設定オプションやコンポーネントの出力を含む破壊的変更は、特別な状況下でのみ許可されます。可能な限り、ユーザーには破壊的変更について事前に通知されるべきです。

Stable

コンポーネントは一般提供（GA）の準備ができています。バグやパフォーマンスの問題は報告されるべきであり（SHOULD）、コンポーネントのオーナーがそれに取り組むという期待があります。設定オプションやコンポーネントの出力を含む破壊的変更は、特別な状況下でのみ許可されます。可能な限り、ユーザーには破壊的変更について事前に通知されるべきです。

Deprecated

このコンポーネントの開発は停止しています。新しいバージョンは計画されておらず、コンポーネントは含まれているディストリビューションから削除される可能性があります。重大なセキュリティ問題を除き、新しいイシューにはおそらく対応されないことに注意してください。ディストリビューションに含まれているコンポーネントは、少なくとも2回のマイナーリリースまたは6か月間のいずれか遅い方の期間、存在し続けることが見込まれます。また、コンポーネントは、「2023-08-01以降の最初のリリース」のように、具体的なバージョン番号やリリース日の観点で、いつ削除されるかを伝えなければなりません（MUST）。

Unmaintained

メンテナンスされていないと識別されたコンポーネントには、アクティブなコードオーナーがいません。このようなコンポーネントには、そもそもコードオーナーが割り当てられたことがない場合もあれば、以前はアクティブだったコードオーナーが連絡を受けてから6週間以内にフィードバックの求めに応じなかった場合もあります。メンテナンスされていないコンポーネントのイシューやプルリクエストには、その旨のラベルが付けられるべきです（SHOULD）。メンテナンスされていない状態が6か月続いた後、これらのコンポーネントは非推奨とされる場合があります（MAY）。メンテナンスされていないコンポーネントは、コードオーナーになってくれるコントリビューターを積極的に募集しています。

トレードオフと緩和策

本OTEPは、SIGのメンテナーが、OpenTelemetryにとってどれが重要かを宣言することなく、SIGの成果物の成熟度を宣言することを認めるものです。これが必要になった場合には、この成熟度レベルを可能なフレームワークとして用いる新しいOTEPが作成される可能性があります。

先行技術と代替技術

仕様のステータスには“コンポーネントライフサイクル”という説明があり、その定義は本OTEPに挙げられている一部のレベルと重複するかもしれません
同じページには、仕様の異なる部分のステータスが一覧化されています
“OpenTelemetryクライアントのバージョニングと安定性”ページには、シグナルのライフサイクルと、OpenTelemetryクライアントによって期待されるべき一般的な安定性の保証について詳しく述べられています。特筆すべきは、Collectorの成熟度に関する情報が欠けている点です。本OTEPは、そのページの最後のセクションである「OpenTelemetry GA」と衝突しているように見えるかもしれません。しかし、そのページがOpenTracingとOpenCensusの両方が非推奨と見なされる時点を確立したのに対し、本OTEPはOpenTelemetryを「stable」と呼ぶための基準を定義し、それを将来の卒業要件とするものです。これにより、プロジェクトのどの部分に頼れるのかがエンドユーザーにとって明確になるでしょう。
OpenTelemetry Collectorには独自の安定性レベルがあり、これが本OTEPのものの着想元となりました
ドキュメント状態の定義
テレメトリーの安定性（experimentalの代わりにunstableを使用しています）

未解決の問題

SDKは、安定していると表示される前に仕様を完全に実装することを要求されるべきでしょうか。open-telemetry/community#2097を参照してください
本OTEPは、すべてのリポジトリが自身の成果物とその成熟度レベルを宣言するために採用すべきファイル名を定義するべきでしょうか

今後の課題

成熟度レベルが広く採用された後、GC/TCは異なるSIGからコンポーネントを選び、CNCF内での卒業提案に進むことを決定するかもしれません。コンポーネントを選択するための意思決定の枠組みは、後の段階で定義されます。