OTEP-0227: セマンティック規約の分離

セマンティック規約をメインの仕様から切り離し、別々にバージョン管理します。

動機

セマンティック規約がOpenTelemetry仕様全体からほぼ独立して進化できるようにする必要があります。 現在、セマンティック規約における破壊的変更は、OpenTelemetry仕様全体のバージョン番号を上げることを必要とします。

説明

OpenTelemetry organization内に、semantic-conventions という新しいGitHubリポジトリが作成されます。

これは 当初 、次のような構造を持ちます。

• README.md、LICENSE、CODEOWNERS、CONTRIBUTING.md などの定型ファイル
• モデルからドキュメントを自動生成できる Makefile
• semantic_conventions/ 現在 {specification}/semantic_conventions に存在するYAMLファイル群
• docs/ セマンティック規約に準拠した計装を作成する方法について、人間が読めるドキュメントを含む新しいディレクトリ
  • resource/ - {specification}/resource/semantic_conventions の内容
  • trace/ - {specification}/trace/semantic_conventions の内容
  • metrics/ - {specification}/metrics/semantic_conventions の内容
  • logs/ - {specification}/logs/semantic_conventions の内容
  • schemas/ - テレメトリースキーマが置かれる新しい場所です。 このディレクトリは https://opentelemetry.io/schemas/ でホストされます。

仕様内の既存のセマンティック規約は、移動したことを示すドキュメントとともに移動済みとしてマークされますが、以前の内容は保持されます。

さらに、セマンティック規約が最終的にドメイン固有のディレクトリ構造（たとえば、トレース、メトリクス、イベントを同一ファイルにまとめた docs/{domain}/README.md など）に移行する場合、これはGitの履歴を保持したまま新しいリポジトリでリファクタリングできます。

また、仕様には次のような例外があります。

• API/SDKの詳細を実装するために使用されるセマンティック規約は、opentelemetry-specification リポジトリで完全に規定され、セマンティック規約ディレクトリでの変更は許可されません。
  • エラー／例外のハンドリングは仕様に残ります。
  • SDKの設定とセマンティック規約とのやり取りは仕様に残ります。 具体的には service.name です。
• 仕様は、互換性要件のために必要に応じて一部のセマンティック規約を格上げすることがあります。 たとえば、service.instance.id や Prometheus互換性 などです。

これらの例外が存在する理由は次のとおりです。

• 仕様の安定した部分は、すでにこれらの規約に依存しています。
• これらの規約は、現在SDKを実装するために必要とされています。

そのため、仕様は、予約または必須の属性名と、それらとSDKとのやり取りについて、絶対的な最小限を定義すべきです。

内部詳細

セマンティック規約が新しい場所へシームレスに移行されることを保証するために、次のプロセスが使用されます。 このプロセスは、手順を順番に列挙したものです。

• 仕様リポジトリへのセマンティック規約に関するPRにはモラトリアムが課されます（ただし、この提案に関連するPRは許可されるという条件付きです）。
• セマンティック規約と仕様の間のやり取りが抽出され、仕様がセマンティック規約に要件を課せるようになり、また 規範的 な仕様の文言はコアの仕様ディレクトリに残ります。
• 提案されたフォーマットと必要な Makefile ／ツール群を備えた新しいリポジトリ open-telemetry/semantic-conventions が構築されます。
  • 新しいリポジトリは、既存のセマンティック規約の履歴をすべて保持するために git filter-branch を使用して作成されます。 つまり、既存のすべてのセマンティック規約が新しいリポジトリに含まれることになります。
  • GitHub Actions、Makefile ツール、およびコントリビューション／READMEは、分離されたリポジトリ用に更新されます。
  • 注記: この時点で、セマンティック規約の新しい場所は採用・利用が可能な状態になっているべきです。
• 仕様内のセマンティック規約は、新しい場所へのリンクとともに移動済みとしてマークされます。
  • 仕様リポジトリ内のsemconv YAMLファイルは 削除されます 。
  • すべてのsemconv Markdownファイルは、次のように更新されます。
    • YAMLファイルからの生成を行わなくなります。
    • 非推奨であることと、新しいリポジトリへの移動を示すヘッダーを含みます。
• 計装の作者は、仕様リポジトリの代わりに新しいsemconvリポジトリから取得するように、コード生成を更新します。

トレードオフと緩和策

この提案にはいくつかの欠点があります。

• セマンティック規約は、仕様から簡単に参照できなくなります。
  • これは実は利点です。 規約を仕様から分離することを保証でき、service.name のような仕様が必要とする属性について、仕様に厳密な文言を使うことを要求できます。
  • 既存の場所から新しい場所へのリンクを提供します。
• セマンティック規約のバージョンは、仕様のバージョンと一致しなくなります。
  • 計装の作者は、仕様バンドルとは別のセマンティック規約バンドルを利用する必要があります。 以前は1つだったアップグレード作業が、2つの（願わくばより小さな）作業に分割されることになります。
  • セマンティック規約と仕様からの変更は直交していると見込まれるため、これによって実時間が大幅に増えることはないはずです。
• セマンティック規約に対する既存のPRは、再生成が必要になります。

当初、このリポジトリは次のような所有権体制を持ちます。

• 承認者
  • Christian Neumüller, Dynatrace
  • James Moessis, Atlassian
  • Joao Grassi, Dynatrace
  • Johannes Tax, Microsoft
  • Liudmila Molkova, Microsoft
  • Sean Marcinak, Atlassian
  • Ted Young, Lightstep
• 承認者（HTTPのみ）
  • Trask Stalnaker
• 承認者（SchemaUrlファイル）
  • Tigran Najaryan
• メンテナー
  • Josh Suereth
  • Armin Ruech
  • Reiley Yang

つまり、メンテナンスは当初、Technical Committee（の一部）が引き続き担うことになります。 承認者は、既存のsemconv承認者に加えて、HTTPセマンティック規約の安定化を対象とする承認者から始まり、セマンティック規約の勢いが高まるにつれて急速に拡大していきます。

先行技術と代替技術

同等のコミュニティや取り組みを評価すると、次のことがわかります。

• OpenTracing - 仕様とセマンティクスが統合されていました。
• OpenCensus - 仕様とセマンティクスが統合されていました。 ただし、OpenCensusは、その仕様が広く採用されたり安定版がリリースされたりする前に、OpenTelemetryと統合されました。
• Elastic Common Schema - スキーマは独自のプロジェクト／ドキュメントとなっています。
• Prometheus - Prometheusは、セマンティック規約のようなテレメトリーに関する厳格なガイドラインを定義しておらず、代わりに命名規則と広範な採用による標準化に依存しています。

未解決の問題

このOTEPは、コミュニティがセマンティック規約を別ディレクトリへ移行するために必要となる、ツールとコード生成のすべてのニーズには対応していません。 これにより、自動生成されたセマンティック規約を使用する各SIGは、新しい場所に適応する必要があります。

セマンティック規約の新しい場所における最初のバージョンは、仕様の最新版に従わない可能性があります。 2.0 を望む理由はありますが、詳細はこのOTEPの実行後、新しいリポジトリの場所で議論されます。

将来の可能性

このOTEPは、次のような望ましい機能への道を開きます。

• セマンティック規約は、仕様のバージョン番号を壊すことなく、新しいシグナルや解決が難しい新しいドメインに対応するために、メジャーバージョン番号を上げることを決定できます。
• セマンティック規約は、専属のメンテナーと承認者を持つことができます。
• セマンティック規約は、対象分野の専門家（SME）が関連ディレクトリで承認者／CODEOWNERのステータスを持てるように、再構成できます。
• セマンティック規約は、それ自体にセマンティックバージョニングを採用でき、ユーザーへの破壊的変更を明確に示すのに役立ちます。

セマンティック規約を、シグナル別ではなくドメイン別のディレクトリに移行したいという要望があります。 これはリポジトリの分離後に行うことができ、このOTEPとは別に提案・議論されます。

たとえば次のとおりです。

• docs/
  • signals/ - メトリクス、トレース、ログの規約
    • http/
    • db/
    • messaging/
    • client/
  • resource/ - リソース固有のセマンティック規約は引き続き必要です