Yoshi Yamaguchi

OTEP-0155: エコシステム管理

より広いコミュニティが計装やその他のパッケージに貢献することを活用する方法についての提案。

動機

OpenTelemetryがオブザーバビリティにおける事実上の標準になるためには、OpenTelemetryがサポートするすべての言語における、さまざまなライブラリやフレームワークとの統合を含む、OpenTelemetryコンポーネントの広大なエコシステムが存在しなければなりません。 これらの統合すべてがOpenTelemetryのコアメンテナーによって提供されることを期待することはできません。 より広いコミュニティが自分たちのプロジェクトをOpenTelemetryと統合してくれることを私たちは望んでいます。 そのためには、統合の作者に対して優れたドキュメント、サンプル、ツールを提供することでそれを奨励する一方で、エンドユーザーに対しては利用可能なすべてのOpenTelemetryコンポーネントを発見し、その品質についてもある程度可視性を持てるような方法を提供する必要があります。

解説

OpenTelemetryレジストリは、プロジェクトのコアメンテナーとサードパーティの両方によって提供される、既知のすべてのOpenTelemetryコンポーネントの中央カタログとして機能します。

コンポーネントがレジストリに含まれるためには、その作者は自己評価フォームに記入しなければなりません。

レジストリは、コンポーネントの所有権、品質、および他のOpenTelemetryコンポーネントとの互換性について、明確な可視性を確保する必要があります。

自己評価フォームのいずれかの宣言に違反し、それが適時に（暫定的には3〜4週間以内に）是正されない場合、そのコンポーネントはレジストリから削除される可能性があります。

内部の詳細

OpenTelemetryコンポーネントおよび統合のソースを、以下のように区別します。

ネイティブまたはビルトインの計装

任意のライブラリやフレームワークは、OpenTelemetry APIを使ってネイティブにテレメトリーを生成できます。 私たちは、ライブラリの作者がOpenTelemetryレジストリへの登録のために自分たちのライブラリを提出することを奨励します。

コアコンポーネント

OpenTelemetryのSIGは、そのSIGのメンテナーが十分に重要だと判断した任意のライブラリに対して計装を提供することがあります。 これを行うことで、SIGのメンテナーは、この計装（そのライブラリの将来のバージョンを含む）をサポートし、アップデートや修正（セキュリティパッチを含む）を提供し、OpenTelemetryのセマンティック規約とベストプラクティスに準拠することを保証することにコミットします。

SIGによっては、こうしたコア計装のインスタンスは、その言語のOpenTelemetry API/SDK実装とリポジトリ、インフラストラクチャ、メンテナーを共有する場合もあれば、別々になっている場合もあります。

コア計装のすべてのインスタンスは、上記で説明した通常のプロセスに従ってOpenTelemetryレジストリに含まれなければなりません。

Contribコンポーネント

任意の言語SIGは、計装エコシステムの特定の部分に関心を持つ開発者によって提供されるコンポーネントを含む、1つ以上の「contrib」リポジトリを持つことがあります。 これらのリポジトリは、コアのAPI/SDKリポジトリとは別の承認者・メンテナーのセットを持つ場合があります。 Contribリポジトリはコアリポジトリと同じくらいプロジェクトの成功にとって重要ですが、同じレベルの専門知識を必要としない場合があります。 実際、これらのリポジトリはしばしば別のスキルセットや顧客理解を求めるものです。 Contribリポジトリの作成時には、他の新規リポジトリと同様に、時間や貢献の要件なしに新しい承認者・メンテナーのセットを追加できます。 リポジトリのメンテナーは、SIG全体のスコープではなく、そのcontribリポジトリに対象を絞った貢献と専門知識に基づいて、貢献者を承認者・メンテナーの役割に昇格させることも奨励されます。 こちらで公開されている正式なガイダンスに従うことで、このプロセスを公平で包摂的なものに保つことが重要です。 Contribリポジトリは、リポジトリ全体への書き込み権限の付与を意味することになったとしても、個々のパッケージにメンテナーを割り当てるためにGitHubのCODEOWNERS機能を活用してよいものとします。 その目標は、コンポーネントの信頼性と全体的な品質、そして公平なガバナンスを維持しながら、PRのレビューや変更の受け入れの負荷をできる限り分散させることであるべきです。

Contribリポジトリ内のすべてのコンポーネントは、上記で説明した通常のプロセスに従ってOpenTelemetryレジストリに含まれることが期待されます。

私たちはすべての貢献を歓迎し、（すべての要件への準拠を含めて）登録のプロセスをできる限り簡単にすべきです。 その目標は、すべての貢献者が自分のコンポーネントを別途ホストするのではなく、contribリポジトリに含めることを奨励することです。 そうすることで、テスト、公開、セキュリティスキャンなどの既存のインフラストラクチャを再利用できます。 また、メンテナーの優先順位が変わった際の責任の移譲も大幅に簡素化されます。 さらに、それぞれの計装ソースに対して単一の計装パッケージの開発とメンテナンスを促進することにもなり、作業が複数の並行するソリューションに分散することを防げます。

言語SIGは、OpenTelemetryが計装に関するセマンティック規約や推奨事項を公開し始めたときに、コンポーネントがそれらに準拠していることを検証するテストハーネスを提供することが奨励されます。

大量のcontribへの貢献は、言語のメンテナーにとって負担となります。これに対処するための提案が2つあります。

  • contrib内に「experimental」フォルダを作成します。 このフォルダの内容は言語リポジトリのメンテナーによってレビューやメンテナンスが行われませんが、contribリポジトリに含まれることによる他の多くの利点はそのまま残ります。 Experimentalな貢献は、レジストリ内でその旨が明示されるべきです。
  • より多くの承認者・メンテナーを追加します。中には、contribへの提出のみに専念する人がいてもよいでしょう。

外部コンポーネント

コンポーネントの作者が、何らかの理由でOpenTelemetryのcontribリポジトリの外部に自分たちの貢献をホストしたい場合、それは自由です（ただし、すべての貢献はcontribまたはコアの言語リポジトリに入れることを私たちは推奨します）。 OpenTelemetryレジストリへの登録の提出も、上記と同じプロセスに従うことで引き続き歓迎されます。

配布

OpenTelemetryコンポーネントがOpenTelemetryレジストリ以外の任意のリポジトリ（npmレジストリやMaven Centralなど）に公開される場合、「OpenTelemetry」の名前空間の下で公開できるのはコアおよびcontribのコンポーネントのみです。 ネイティブおよび外部のコンポーネントは、それぞれ独自の名前空間の下で公開されるものとします。

OpenTelemetryのSIGが何らかの「オールインワン」計装ディストリビューション（Javaや.NETが行っているような）を提供する場合、コアおよびcontribパッケージのみを含むディストリビューションを取得できるオプションがあるべきです。 OpenTelemetryレジストリは、これらのコンポーネントの一覧を簡単に取得できる方法を提供すべきです。 SIGは他のディストリビューションを提供してもかまいません。 可能であれば、SIGは、対象アプリケーションのビルド時またはランタイムに任意の外部コンポーネントを組み込むためのメカニズムを提供すべきです。 これは、すべてのコンポーネントが実装することを奨励される、言語固有のコンポーネントAPIを意味する場合があります。

トレードオフと緩和策

  • contribリポジトリでマージ権限を取得することがどれくらい容易であるべきか。 それが難しいほど、コアチームにかかるメンテナンスの負担は大きくなります。 それが容易であるほど、貢献の品質についての不確実性は大きくなります。 これは各言語SIGがそれぞれで決めてよいことなのか、それとも私たちが一緒に決めるべきことなのか。

未解決の問題

レジストリ自己評価フォーム

正確な項目リストは別途策定されるべきですが、少なくともコンポーネントの作者は以下を宣言する必要があります。

  • CNCFによって承認された寛容なOSSライセンスを使用していること
  • 既知のセキュリティ脆弱性がないこと
  • OpenTelemetryのセマンティック規約に準拠したテレメトリーを生成すること
  • OpenTelemetry/SIGが生成されたテレメトリーを検証するためのテストハーネスを提供している場合、そのテストが使用され、合格したこと
  • 作者がこのコンポーネントの将来のメンテナンスに合理的な労力をコミットすること

レジストリにおけるコンポーネント情報

レジストリにおけるコンポーネントページの正確なUIはこのOTEPのスコープ外ですが、いくつかの提案を以下に示します。

  • コンポーネントの簡単な説明
  • このコンポーネントの元のリポジトリへのリンク
  • コンポーネントの作者・メンテナーおよびそのOpenTelemetryステータス（ネイティブ/コア/contrib/外部）の明確な表示
  • 使用されているライセンス
  • 言語と対象ライブラリ
  • 現在のイシューおよび既知のセキュリティ脆弱性の一覧へのリンク
  • 評価や星、サムズアップ/ダウンなど、利用者から見たコンポーネントの品質を示す何らかの方法
  • このコンポーネントがテストされたOpenTelemetry API/SDKおよびライブラリのバージョン
  • このコンポーネントによってOpenTelemetryの検証ハーネスが使用されているかどうか
  • 記入済みの自己評価フォーム
  • 標準化したいと考えられる任意の品質指標（テストカバレッジなど）
  • 開発統計（作成日、最終リリース日、最終コミット日）