> Source: https://www.ymotongpoo.com/works/oteps/otep-0243/


# OTEP-0243: OpenTelemetryにおけるアプリケーションテレメトリースキーマの導入 - ビジョンとロードマップ

----
**著者**: Laurent Querel, F5 Inc.

**キーワード**: スキーマファーストアプローチ、テレメトリースキーマ、セマンティック規約、
発見可能性、相互運用性、型安全なクライアントSDK、クライアントSDK生成、
CI/CD統合、データガバナンス、データプライバシー。

**関連OTEP**: [OTEP0152](0152-telemetry-schemas.md)、[OTEP0202](0202-events-and-logs-api.md)。

----
_従来のデータエコシステム（OLTPやOLAP）とは異なり、テレメトリーの世界では一般に、スキーマという概念に依存していません。
計装はアプリケーションやライブラリのコードに深く埋め込まれているため、あるアプリケーションが発しうるすべてのテレメトリーシグナルを事前に発見することは困難です。
このギャップは、アプリケーション固有のテレメトリーシグナルをチェックし、レポートし、ドキュメント化し、そこから成果物を生成するCI/CDツールの開発を妨げたり、制限したりします。
本書では、OpenTelemetryプロジェクトがこの課題に取り組み、より広いエコシステムにその効果を拡張することを目指す長期的なビジョンを提示します。
本書は、Telemetry SchemaとSemantic Conventionsという既存の取り組みを拡張し、Component Telemetry SchemaとResolved Telemetry Schemaという論理的な概念を含めることを提案します。
このビジョンの各側面を詳述するために、一連のOTEPとツールが本書の中で提案されます。_

## 現状の概観 {#current-state-overview}

従来、アプリケーションの計装は、アプリケーションおよびそのコンポーネントのソースコードに深く統合されてきました。
OpenTelemetryの現在のスタックはこのアプローチに従っており、このエコシステムがSDKを通じて汎用的なクライアントインターフェースと共通のプロトコルによってテレメトリーデータを共同で報告できる統一的な仕組みを提供しています。
さらに、OpenTelemetryのセマンティック規約は、ベンダーに依存しない標準化された語彙を確立し、時間の経過とともにより一貫性のある計装を保証します。
この標準化により、テレメトリーパイプライン全体にわたってこれらのメタデータの分析と活用が容易になります。

しかし、このアプローチには課題がないわけではありません。

* **発見可能性と相互運用性**: あるアプリケーション全体がテレメトリーおよび関連メタデータとして具体的に何を生成するのかを、事前かつ自動的に発見することは困難です。
  これにより、企業のデータカタログ、コンプライアンス手続き、または _CI/CDパイプライン_ における自動化されたプライバシー適用との統合が困難になります。
* **ユーザー体験**: 非常に柔軟ではあるものの、汎用的なクライアントは強く型付けされた専用APIと同じ利点を提供しません。
  型安全なAPIは、より人間工学的で、より堅牢で、より保守しやすいものです。
  現代のIDEは、APIに基づいてスマートな自動補完とコンテキストに応じたドキュメントを提供できます。
  コンパイラーは、テレメトリースキーマのリファクタリングや進化の際に発生するエラーを自動的に検出できます。
* **拡張性**: 基本的なシグナル仕様にメタデータを追加することは、データセキュリティ、プライバシー適用、メタデータ駆動のデータ変換、ナレッジグラフの拡充といったユースケースを可能にするために不可欠です。
  現在、アプリケーションやライブラリの開発サイクルとは別にメタデータを追加する標準的な方法はありません。
  これらのメタデータの定義はシグナル定義とは異なるべきものであり、開発チーム以外のチームによって指定される可能性もあります。
* **パフォーマンスオーバーヘッド**: 汎用的なテレメトリー計装の大きな欠点は、そこに内在する抽象化レイヤーに起因して一般に生じるさまざまなオーバーヘッドです。
  たとえば、属性の集合は通常、キーと値のペアのリストやハッシュマップとして表現され、メモリオーバーヘッドが生じます。
  単純な構造体や、型付けされた関数パラメーターの集合の方が、この属性のリストを表現するにはより効率的でエラーが起きにくいでしょう。
  同様に、値の取りうる範囲がスキーマ定義内で列挙型の形で指定されている場合、その値には辞書エンコーディングを使用することが可能です。

データベースやRPCシステム（protobufやgRPCなど）は、スキーマファーストアプローチによってこれらの課題の一部にすでに対処しています。
テレメトリーの文脈で同様のアプローチを採用することを妨げるものは何もありません。
**本書では、OpenTelemetryプロジェクトにスキーマファーストアプローチを適用する方法と、それが既存のTelemetry SchemaおよびSemantic Conventionsに与える影響について論じます。**

## 可能な／望ましい将来の姿 {#possibledesired-future-state}

以下の図は、将来のスキーマ駆動のエンドツーエンドテレメトリーシステムの典型例となりうるものにおける、さまざまなコンポーネント、プロセス、成果物の関係についての概念的な概要を示しています。

![Application Telemetry Schema Overview](img/0243-otel-weaver-overview.svg)

Application Telemetry Schemaという概念は、前掲の図に示すように、Component Telemetry SchemaとResolved Telemetry Schemaという2つの主要な論理的部分に分かれています（この2つの概念の詳細は提案のセクションで述べます）。
これらの概念は、さまざまなユースケースを実現するための中心となるものです。

ユースケースの例としては、次のようなものがあります。

* テレメトリースキーマからテレメトリークライアントSDKを自動生成し、ユーザー体験とパフォーマンスを改善する。
* CI/CDパイプラインがテレメトリースキーマを次の目的で使用する。
  * 異なるスキーマバージョン間の互換性をチェックする。
  * セキュリティおよびプライバシーへの準拠を確保する。
  * 企業のデータカタログシステムと統合する。
  * その他。
* テレメトリーバックエンドが次のことを可能にする。
  * データベーススキーマやダッシュボードを自動的に更新する。
  * ストリームプロセッサーにおいてスキーマ駆動の変換や処理をトリガーする。
  * その他。

[data.world](https://data.world/home/)による最近の[論文](https://arxiv.org/pdf/2311.07509#:~:text=The%20results%20of%20the%20benchmark%20provide%20evidence%20that%20supports%20our,LLM%20without%20a%20Knowledge%20Graph)、および[dbt Semantic Layer](https://www.getdbt.com/product/semantic-layer)の基盤となっている[MetricFlowフレームワーク](https://docs.getdbt.com/docs/build/about-metricflow)は、特に生成AIによる質問応答システムにおいて、データモデリングにスキーマファーストアプローチを採用することの重要性を強調しています。
[Elastic AI Assistant](https://www.elastic.co/fr/blog/introducing-elastic-ai-assistant)や[Honeycomb Query Assistant](https://www.honeycomb.io/blog/introducing-query-assistant?utm_source=newswire&utm_medium=link&utm_campaign=query_assistant)といったObservability Query Assistantのようなツールは、スキーマファーストアプローチの採用によって、近い将来ますます普及し、効率化していくと考えられます。

> [!NOTE]
> これらの概念の名称とフォーマットは、まだ議論の途中です。
> 長所と短所の詳細な分析は本書の後半で扱います。
> 最終的な決定は今後の専用のOTEPに委ねられます。

本提案が取り組もうとしているもう一つの問題は、OpenTelemetryが利用されているものの既存のソリューションでは十分に対応できていない、このエコシステムに内在する複雑さです。
OpenTelemetryはあらゆる規模の企業に採用されています。
標準化されたセマンティック規約を継承できることは有益ではあるものの、多様な文脈でのカスタマイズ（たとえば要求レベルをrecommendedからrequiredに変更するなど）の必要性から、それだけではしばしば不十分であることが判明しています。
さらに、既存の公式OpenTelemetryセマンティック規約レジストリにベンダー固有の属性やメトリクスが存在することは、ベンダーに依存しない属性・メトリクス・シグナルのカタログを提供するという目標とは相容れません。
**これらの問題は、スキーマとセマンティック規約レジストリのエコシステムを拡張・カスタマイズ・発展させるための標準化された仕組みが欠けていることを示しています。**

これらの問題に対応するため、もっとも一般的なものから、あるアプリケーション向けに特に洗練されたものまで、テレメトリースキーマの階層を定義することができます。
それぞれの子スキーマは親スキーマのプロパティを継承し、必要であればこれらのプロパティをローカルでオーバーライドすることができます。
さらに、任意のテレメトリースキーマは1つまたは複数のセマンティック規約レジストリをインポートできるため、OpenTelemetryのレジストリ、ベンダー固有のレジストリ、企業レベルのレジストリを定義することが可能になります。
これら2つの拡張により、OpenTelemetryはよりカスタマイズ可能で、拡張性が高く、エコシステムに親和的なものになります。

次のセクションでは、Component Telemetry Schema、Resolved Telemetry Schema、Semantic Convention Registryの概念、そしてこれらと既存のOpenTelemetry Schema v1.1およびOpenTelemetry Semantic Conventionsとの関係について詳しく説明します。

## 提案 {#proposal}

### 概要 {#overview}

概念的には、本提案は**Component Telemetry Schema**、**Semantic Convention Registry**、**Resolved Telemetry Schema**という3つの主要な概念に基づいています。
これらのエンティティ間の関係は次の図に示されています。

![Telemetry Schema Concepts](img/0243-otel-weaver-concepts.svg)

Component Telemetry Schemaは、OpenTelemetryのSIGメンバー、アプリケーションやライブラリの作者によって作成されます。
Component Telemetry Schemaは、必要に応じて任意の数のSemantic Convention Registryをインポートできます。
スキーマの解決処理の過程で、Component Telemetry SchemaからResolved Telemetry Schemaが作成されます。
この**Resolved Telemetry Schemaは自己完結的**であり、外部参照を持ちません。
オプションとして、Component Telemetry Schemaは既存のTelemetry Schema（componentのものであれresolvedのものであれ）を拡張することができます（この点はまだ議論中です）。
一般的には、公式のOpenTelemetry Telemetry Schemaが標準のOpenTelemetry Semantic Convention Registryを含めるためにComponent Telemetry Schemaに継承されます。
複雑なケースでは、大企業がカスタム定義のために独自の中間的なテレメトリースキーマを作成することもあります。

Component Telemetry Schema内で定義された各シグナル定義は、可能な限り、セマンティック規約によって定義された既存の構文とセマンティクスを再利用します。
各シグナル定義は一意な名前（またはID）によっても識別されるため、スキーマをアドレス可能にし、走査、検証、diffを容易にします。

Resolved Telemetry Schemaの定義において従うべき主要な設計原則は次のとおりです。

* **自己完結的**: 外部参照は許可されません。
  この成果物には、あるアプリケーションまたはライブラリがテレメトリーとして何を生成するかを判断するために必要なすべてが含まれています。
* **交換が容易**: この成果物は、URIを通じて関係者が容易にアクセスできなければなりません。
  この成果物は小さく、定義の重複を避けなければなりません。
* **パースが容易**: 広く普及した明確に定義されたフォーマットが望ましいです。
  JSONはそのようなフォーマットの一例です。
* **解釈が容易**: この成果物の内部構造は、誤解釈を避けるために単純明快でなければならず、効率的でなければなりません。
* **プラットフォームおよび言語に依存しない**: この成果物は、いかなるプラットフォームアーキテクチャやプログラミング言語にも依存してはなりません。

次の図は、Resolved Telemetry Schemaの2つの主要なユースケースを示しています。
覚えておくべき重要な点は、1) どちらのユースケースもResolved Telemetry Schemaという結果になること、2) Resolved Telemetry Schemaはエコシステム全体にTelemetry Schemaを配布するための仕組みとして機能すること、3) Resolved Telemetry Schemaは既存のSchemaURLを置き換えるか拡張することです。

![Use cases](img/0243-otel-weaver-use-cases.svg)

注: Telemetry Schema v1.1（[OTEP 0152](0152-telemetry-schemas.md)）と、ComponentおよびResolved Telemetry Schemaの概念との関係は、まだ議論中です。
これは今後のOTEPで明確化されます（最後のセクションを参照してください）。

次の図は、スキーマとセマンティック規約レジストリの複雑な階層のありうる例を示しています。
これは、標準化されたOpenTelemetryの成果物に加えて、いくつかのベンダーおよび企業の成果物を含みます。
スキーマの解決処理は、Client SDK Generator、互換性チェッカー、コンプライアンスチェッカー、データカタログフィーダーなど、さまざまなツールやアプリケーションから容易に利用できる自己完結的なResolved Telemetry Schemaを生成します。

![Example of Telemetry Schema Hierarchy](img/0243-otel-weaver-hierarchy.svg)

このテレメトリースキーマの階層は、大規模な組織がComponent Telemetry Schemaで協業する際に役立ちます。
これにより、Component Telemetry Schemaのさまざまな側面を、異なるチームが管理できるようになります。

Component Telemetry Schemaを構成するすべての要素に対して、追加の特性、性質、制約を付与できるようにするための注釈またはタグ付けの一般的な仕組みが統合され、ベンダーや企業がOpenTelemetryによって定義された概念の定義を拡張できるようになります。
この注釈の仕組みは、Component Telemetry Schemaの定義の一部として含まれます。

注釈とタグは、多様な読者に向けてスキーマを変更するためにも使用できます。
たとえば、スキーマの公開版では、privateとラベル付けされたすべてのシグナルやその他のメタデータを除外することができます。
同様に、要素をベータテスター専用として指定することもできます。
これらの注釈は、属性をPII（個人を特定できる情報）として識別することにも使用でき、プライバシーポリシーの適用をさまざまなレベル（生成されたクライアントSDK内やプロキシ内など）で実装することができます。

次の図は、重要な各コンポーネントについて、ComponentおよびResolved Telemetry Schemaを定義する今後のOTEPで検討される責務と主要な設計プロパティを定義しています。

![Telemetry Schema - Levels of responsibilities & Key design properties](img/0243-otel-weaver-responsibilities-properties.svg)

この設計により、セマンティック規約を分散的な方法で定義することが可能になります。
OpenTelemetry、ベンダー、企業は、それぞれ異なるレジストリで独自のセマンティック規約を定義でき、既存のプロセスが簡素化されます。

> これらのシステムの間に直接の系譜はありませんが、同種の問題に対処するために、独自の（プロプライエタリな）文脈でFacebookによって設計・展開された同様のアプローチが存在します（詳細はこの[ポジションペーパー](https://research.facebook.com/publications/positional-paper-schema-first-application-telemetry/)を参照してください）。

### 開発戦略 {#development-strategies}

2つの開発戦略が共存しており、どちらもサポートされなければなりません。
第一の戦略はモノレポ型（単一のソースオブトゥルース）であり、アプリケーション、その依存関係、および関連するテレメトリースキーマを完全に制御下に置きます。
第二の戦略はより異種混合的なもので、複数のリポジトリから構成され、外部依存関係のビルドプロセスは、アプリケーションやサービスを所有するエンティティの制御外にあります。

第一のモデルでは、ポリシーが共有されており、環境全体が同一のエンティティによって制御されていることが分かっているため、それぞれのビルドプロセスがテレメトリースキーマのポリシーを並行して独立に適用できます。

第二のモデルでは、アプリケーションやサービスの環境は、外部依存関係のテレメトリースキーマポリシーを制御しません。
これらの依存関係からテレメトリースキーマを取得する方法が必要になります。
これらのスキーマを配布する仕組みについては、まだ議論が続いています（Open Questionsのセクションを参照してください）。
最終的には、これにより、アプリケーションやサービスのCI/CDパイプラインが、依存関係から得られたこれらのスキーマに対して自身のローカルなポリシーを適用できるようになります。

![Development Strategies to Support](img/0243-otel-weaver-dev-strategies.svg)

## 未解決の課題 {#open-questions}

本書のレビューの過程でいくつかの疑問が提起され、その一部は未解決のままです。
私たちは、これらの未解決の課題への回答を今後のOTEPに先送りすることに決めました。
これらの課題の解決は現段階では重要ではなく、今後のOTEPを定義・実装していく中でより明確になっていくと考えられるため、このアプローチのほうが実践的だと思われます。

### 単一のTelemetry Schemaを使うべきか、それともComponent Telemetry SchemaとResolved Telemetry Schemaの組み合わせを使うべきか {#should-we-use-a-single-telemetry-schema-or-the-combination-of-component-and-resolved-telemetry-schema}

単一のTelemetry Schemaを採用するか、ComponentとResolvedの別々のTelemetry Schemaを採用するかという議論は未解決のままです。

単一スキーマアプローチの支持者は、これがスキーマの定義、実装、さらには認知負荷の面での簡素化になると考えています。
彼らは、同じスキーマを使いつつ、第三者への公開・再利用を意図したスキーマについては外部参照を禁止することを提案しています。
スキーマの解決処理は、その後これらの参照を除去することになります。

2種類のスキーマアプローチの支持者は、それぞれのフォーマットが異なる利用者・ユースケース（アプリ／ライブラリの開発者 対 テレメトリーツールの開発者）を対象としていると考えており、したがって、2つの異なる構造とフォーマットを持つことで、それぞれをその特定のユースケースに向けて（複数の観点から）最適化しやすくなるとしています。
さらに、Component Telemetry Schemaを使用する開発者の集団は、Resolved Telemetry Schemaの詳細を理解する必要がある開発者の集団よりも、おそらくはるかに大きくなるでしょう。

### スキーマの名称はどうあるべきか {#what-should-be-the-schemas-be-named}

スキーマの名称についても議論されましたが、合意には至っていません。
現在の提案は次のとおりです。

- 単一スキーマアプローチ: 既存のTelemetry Schemaという名称を維持しつつ、ユースケースに応じて異なるフォーマットをサポートする（たとえば、アプリ／ライブラリの開発者向けにはYAML、公開やツールでの利用にはJSON + JSON Schemaなど）。
- 2種類のスキーマアプローチ:
  - Component Telemetry Schemaの代替名: Telemetry Schema、Weaver Schema。
  - Resolved Telemetry Schemaの代替名: Compiled Telemetry Schema、Published Telemetry Schema、Weaver Schema。

### 依存関係のスキーマを取得するためにどのような配布の仕組みを使うべきか {#what-distribution-mechanism-should-be-used-for-retrieving-dependency-schemas}

現在、主に次の2つの方法が検討されています。

1) resolved schema向けの、パブリックで集中管理されたリポジトリを構築し、ライブラリの作者がビルドプロセスの一部として自分たちのresolved telemetry schemaを登録できるようにする。
2) Resolved Telemetry Schemaを（バイナリライブラリ、jarファイル、crate、Goモジュールなどの）ライブラリの成果物に直接埋め込み、アプリケーションのビルドプロセス中に自動的に収集されるようにする。

現時点では、完全に分散化されており、グローバルなスキーマレジストリが不要になるという理由から、第2の選択肢が好まれています。
この配布の仕組みを定義するための専用のOTEPが作成される予定です。

## ロードマップ {#roadmap}

### OTEP {#oteps}

レビュープロセスを容易にし、OpenTelemetryコミュニティに段階的に価値を届けるために、一連のOTEPとツールが提案されています。

* **Telemetry Schema(s) - Structure and Formats**: このOTEPでは、単一スキーマと2種類のスキーマのアプローチのそれぞれの長所と短所を比較検討します。
  最適な解決策を特定し、本書で導入された2つの概念、すなわちComponentおよびResolved Telemetry Schemaの構造とフォーマットを定義することを目指します。
  本書で論じられている概念を段階的に導入・実施するために、複数のサブOTEPを計画しています。
  * **フェーズ1**: 既存のセマンティック規約レジストリから完全に解決された属性、メトリクス、その他のテレメトリーシグナルのリストを含むレジストリセクションを導入します。
  実装後、OpenTelemetryプロジェクトのテレメトリースキーマには、セマンティック規約によって定義された、標準化されたすべての属性・メトリクス・シグナルのレジストリが含まれるようになります。
  * **フェーズ2**: あるアプリケーション（およびその依存関係）やライブラリが発するテレメトリーシグナルを表現するための、リソース、計装ライブラリ、スキーマの各セクションを追加します。
  当初は、メトリクス、ログ、スパンの定義のみがサポートされます。
  * **フェーズ3**: アプリケーションやライブラリの作者が、親のresolved schemaから継承した定義をオーバーライドできるようにします。
  * **フェーズ4**: OpenTelemetryでイベントが承認されることを前提に、スキーマセクションにおけるイベントのサポートを実装します。
  * **フェーズ5**: Client SDK Generatorが多変量メトリクスをサポートする計画がある場合にのみ関係する、スキーマセクションにおける多変量メトリクスのサポートを導入します。
* **Dependency Management and Telemetry Schema Distribution**: このOTEPでは、依存関係からresolved telemetry schemaを収集する方法について概説します。

### 概念実証とツール {#proof-of-concept-and-tools}

提案されたアプローチの実現可能性を検証するために、概念実証であるOTel Weaverが開発中です。
これは次のコマンドをサポートする予定です。

* `resolve registry`: OpenTelemetryセマンティック規約レジストリからResolved Telemetry Schemaを生成します。
* `resolve schema`: Component Telemetry SchemaからResolved Telemetry Schemaを作成します。
* `search registry`: OpenTelemetryセマンティック規約レジストリ内での検索機能を提供します。
* `search schema`: ComponentまたはResolved Telemetry Schema内での検索機能を提供します。
* `gen-client sdk`: ComponentまたはResolved Telemetry SchemaからClient SDKを生成します。
* `gen-client api`: ComponentまたはResolved Telemetry SchemaからClient APIを生成します。

OTel Weaverツールへのコミュニティからの貢献を可能にするために、プラグインシステムが計画されています。
提案されているプラグインには次のものがあります。

* 外部の依存関係からresolved telemetry schemaを収集するためのプラグインの例。
* 同一のTelemetry Schemaの連続するバージョンが指定された互換性ルールに従っていることを保証する、互換性チェッカープラグインの例。

Resolved Telemetry Schemaの標準化されたフォーマットとOTel Weaver Plugin Systemを活用して、コミュニティ全体によって追加のプラグインやツールが開発されることが見込まれています。

## リンク {#links}

- [Positional Paper: Schema-First Application Telemetry](https://research.facebook.com/publications/positional-paper-schema-first-application-telemetry/)
- [A benchmark to understand the role of knowledge graphs on Large Language Model's accuracy for question answering on enterprise SQL databases](https://arxiv.org/pdf/2311.07509#:~:text=The%20results%20of%20the%20benchmark%20provide%20evidence%20that%20supports%20our,LLM%20without%20a%20Knowledge%20Graph)
- [MetricFlow framework](https://docs.getdbt.com/docs/build/about-metricflow)