OTEP-0199: Elastic Common SchemaをOpenTelemetryセマンティック規約にマージする

Introduction

この提案は、Elastic Common Schema（ECS）をOpenTelemetryセマンティック規約（SemConv）にマージし、OpenTelemetryコンポーネントの実装において完全な相互運用性を提供するものです。私たちは、可能な限りOpenTelemetryセマンティック規約をECS FieldSetsに整合させ、また逆方向にも整合させることでこれを実現することを提案します。長期的な目標は、ECSとOTelセマンティック規約を単一のオープンなスキーマへと収束させ、OpenTelemetryセマンティック規約が名実ともにElastic Common Schemaの後継となることです。

The Goal

長期的には、ECSとOTel SemConvはOpenTelemetryによって保守される単一のオープンな標準へと収束します。この取り組みを開始するにあたり、Elasticは新しい標準の保守を助けるために、複数のドメインエキスパートをOpenTelemetryセマンティック規約のApproverとして指名します。
OTel SemConvは、ロギング、オブザーバビリティ、セキュリティドメインのフィールドを含め、（避けられない個別の詳細な調整を除いて）ECSの範囲全体を採用し、新しいスキーマをECSとOTel SemConvの真の後継とします。
ElasticとOpenTelemetryは連携し、（公式サイトやブログ記事などを通じて）マージの方向性を正式に発表します。
ECSとOTel SemConvのユーザーを時間をかけて新しい共通スキーマへ移行させ、その移行をできるだけ簡単にするためのユーティリティを提供します。

Scope and Overlap of ECS and OTel SemConv

ECSとOTel SemConvには現在いくつかの重複がありますが、互いを補強し合う重要な領域も存在します。以下の図は、それぞれの領域を示しています。

A：ECSには、幅広いロギング、オブザーバビリティ、セキュリティのユースケースをカバーする豊富なフィールドセットが備わっています。多くのフィールドはOTel SemConvに対して追加的であり、大きな衝突を起こすことなくOTel SemConvを補強します。例として、Geo情報フィールド、Threatフィールドなどが挙げられます。
B：逆に、OTel SemConvにはECSには存在せず、ECSを補強することになる属性があります。例として、メッセージングセマンティック規約や、AWS SDK規約のような技術固有の規約が挙げられます。
C：ECSとOTel SemConvの間には重要な重複領域があります。領域Cは、ECSとOTel SemConvで非常によく似ているフィールド／属性の重複を表しています。 Cにおけるフィールドの衝突は、単純なフィールドのリネームと単純な変換によって解決できます。
D：一部のフィールドや属性については、単純なリネームや変換では解決できない衝突があり、スキーマをマージする目的でECSまたはOTel SemConv側に破壊的変更を導入する必要があります。

Proposed process to merge ECS with OTel SemConv

ECSとOTel SemConvをマージするプロセスには時間がかかるため、私たちはこれをOTel SemConvの安定化の取り組みの一部として実施することを提案します。この期間中、そしてマージ後も相当の期間（サンセット期間）にわたって、Elasticはスキーマとしてのサポートを継続します。ただし、ECSのさらなる進化は、新しい共通スキーマを基盤として行われます。 Elasticは、新しいスキーマの保守を助けるためにECSのエキスパートを指名し、その新しいスキーマのためにOpenTelemetryのセマンティック規約のApprover役割を必要とします。

マージに伴い、ECSのフィールドとOTel SemConvの属性の間には（上図に示したように）さまざまなカテゴリのフィールドの衝突が生じます。領域AとBは議論の余地が少なく、補強された新しいスキーマにとって手を付けやすい部分になると考えています。

領域CとDについては、OTel SemConvの安定化イニシアチブの一環として、緊密な協力を通じて衝突を解決することを提案します。可能な場合には、OTel SemConvの属性を既存の安定したECSのフィールドにできる限り近づけることを目標とします。整合が難しい場合には、技術的な変換やエイリアシングを通じてフィールドの衝突に対処する方法を見出し、（たとえばOpenTelemetry Collectorのプロセッサーを通じて）既存のフィールドやフォーマットを新しいスキーマへ、また逆方向にも橋渡しすることを目標とします。

現実的には、マージの過程でECSとOTel SemConvに真に破壊的な変更を避けることはできませんが、それは最後の手段とすべきであり、フィールドごとに議論する必要があります。

Motivation

Elastic Common Schema（ECS）をOpenTelemetry（OTel）に追加することは、ベンダーが作成したロギングとOTelコンポーネントのログ（すなわちOTel Collectorのログレシーバー）の統合を加速させる優れた方法です。その目標は、もっとも一般的な種類のシステムに対してベンダー中立なセマンティック規約を定義し、ベンダーが作成した、あるいはオープンソースのコンポーネント（たとえばHTTPアクセスログ、ネットワークログ、システムアクセス／認証ログ）をサポートし、OTelの相関関係をこれらの新しいシグナルに拡張することです。

ECSのカバレッジをOTelに追加することは、OpenTelemetry Collectorのログレシーバーの作成者にガイダンスを提供し、OTel Collectorを、より豊かなデータ定義を可能にする明確に定義されたスキーマを持つデファクトスタンダードなログコレクターとして確立する助けとなります。

構造化ログのユースケースに加えて、SIEM（Security Information and Event Management）向けのECSの成熟度は、OpenTelemetryがそのスコープをセキュリティのユースケースへと拡張する絶好の機会です。

もう一つの重要なユースケースは、Kubernetesのアプリケーションログ、システムログ、アプリケーションのイントロスペクションイベントに対してファーストクラスのサポートを提供することです。また、構造化イベント（たとえばk8seventsreceiver）のサポートや、イベントの種類を識別するための「content-type」の利用も実現したいと考えています。

さまざまなカテゴリの構造化ログが、おそらくログ属性のためのセマンティック規約を通じて、OTelログデータモデルで十分にサポートされることを望んでいます（ログ属性のセマンティック規約）。たとえば、NGINXのアクセスログとApacheのアクセスログは、構造化ログとして同じように処理されるべきです。これは、こうしたログデータとのトレースおよびメトリクスの相関関係に役立つだけでなく、オブザーバビリティバックエンドや監視ダッシュボードが提供するキュレーションされたUIのエコシステムの成長にも役立ちます（たとえば、Apache httpd、NGINX、HAProxyに恩恵をもたらす単一のHTTPアクセスログダッシュボードなど）。

Customer Motivation

ECSを共通標準として活用し、これを正規化の基盤とすれば、OTelログの採用は大きく加速します。この対応により、OTelログの採用は加速します。たとえば、ECSはベンダーが生成したログとオープンソースのログを扱うための統一された構造化フォーマットを提供できます。

顧客は、OTel互換のオブザーバビリティ製品やサービスによって完全に認識される、すぐに使えるログ統合の恩恵を受けることができます。

現在、OpenTelemetryのロギングは、計装ライブラリが使われている場合はほとんどが構造化されています。しかし、現在存在するログの大半は、ユーザーが制御できないソフトウェア、ハードウェア、クラウドサービスによって生成されています。 OpenTelemetryは、ログを構造化するための限られた「リファレンス統合」のセットを提供しています。これには主に、OpenTelemetry CollectorのKubernetesイベントレシーバーや、OpenTelemetry Collectorのファイルレシーバーを使った正規表現ベースのTomcatアクセスログのパース例（こちら）が含まれます。 ECSですでに定義されている追加の名前空間でOTelセマンティック規約を拡張することにより、さまざまなソースからのこうしたマッピングをより広くカバーし、OTel Collectorで定義・実装できるようになります。これには、たとえば、ネットワーク機器からのログ（ECSのnetworkおよびinterface名前空間へのマッピング）が含まれます。

ログのセマンティック規約は課題です。ログの中で定義される特定のコンポーネントとは何であり、同じ意味的なコンポーネントが異なる形で定義されている他のログとどのように関連するのでしょうか。 ECSは、OTelで採用できる統一されたセマンティック規約のセットを定義するという骨の折れる作業をすでに行っています。

OpenTelemetryは、こうした他のサービスからのデータを計装されたコードやコンポーネントと相関させることができれば、指数関数的に成長する可能性を秘めています。これを実現するために、業界の関係者は、こうした異なるデータ型のマッピングを可能にする共通の標準的なロギングデータモデルを活用すべきです。 OpenTelemetryのデータプロトコルは、この相互運用可能なオープンな標準を提供できます。これにより無数のユースケースが可能になり、OpenTelemetryがOpenTelemetry準拠でない他の技術とも連携できるようになります。

Background

What is ECS?

Elastic Common Schema（ECS）は、Elasticのユーザーコミュニティのサポートを受けて開発されたオープンソースの仕様です。 ECSは、ログ、メトリクス、セキュリティおよび監査イベントなど、Elasticsearchにデータを保存する際に使用される共通のフィールドセットを定義します。 ECSの目標は、Elasticsearchのユーザーがイベントデータを正規化できるようにし、それを促進することで、イベントに表現されたデータをより良く分析、可視化、相関できるようにすることです。詳細については以下を参照してください。https://www.elastic.co/docs/reference/ecs

ECSのカバレッジは非常に広く、「logs.*フィールド」、「geo.*フィールド」、「tls.*フィールド」、「dns.*フィールド」、「vulnerability.*フィールド」など、ログ、セキュリティ、ネットワークイベントに対する詳細なサポートを含みます。

ECSには次のような指導原則があります。

ECSは、多くのフィールドがリファレンスでその意味を調べなくても理解できるよう、より広い採用を可能にするために人間にとっての読みやすさを重視しています。
ECSのイベントには、（ホスト、データセンター、Dockerイメージ、IPアドレスなど）あらゆる次元での相関関係を可能にするメタデータが含まれます。
- ECSは、OTelがResource属性とLog／Span／Metrics属性を区別するのとは異なり、イベントソースの各イベントに固有のメタデータフィールドと、そのソースのすべてのイベントで共有されるメタデータとを区別していません。
ECSは、次の目的のためにフィールドを名前空間にグループ化しています。
- 一貫性と読みやすさを提供する。
- さまざまなコンテキストで名前空間を再利用できるようにする。
  - たとえば、「geo」名前空間は「client.geo」、「destination.geo」、「host.geo」、「threat.indicator.geo」の各名前空間の中にネストされています。
- 名前空間へのフィールドの追加や新しい名前空間の追加によって拡張性を実現する。
- フィールド名の衝突を防ぐ。
ECSは、セキュリティおよびネットワークイベントの詳細なカバレッジを含む40以上の名前空間で、幅広いイベントをカバーしています。これは、単純なロギングのユースケースよりもはるかに広範囲です。

Example of a log message structured with ECS: NGINX access logs

ECSで構造化されたNGINXアクセスログエントリーの例

{
   "@timestamp":"2020-03-25T09:51:23.000Z",
   "client":{
      "ip":"10.42.42.42"
   },
   "http":{
      "request":{
         "referrer":"-",
         "method":"GET"
      },
      "response":{
         "status_code":200,
         "body":{
            "bytes":2571
         }
      },
      "version":"1.1"
   },
   "url":{
      "path":"/blog"
   },
   "user_agent":{
      "original":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36",
      "os":{
         "name":"Mac OS X",
         "version":"10.14.0",
         "full":"Mac OS X 10.14.0"
      },
      "name":"Chrome",
      "device":{
         "name":"Other"
      },
      "version":"70.0.3538.102"
   },
   "log":{
      "file":{
         "path":"/var/log/nginx/access.log"
      },
      "offset":33800
   },
   "host": {
     "hostname": "cyrille-laptop.home",
     "os": {
       "build": "19D76",
       "kernel": "19.3.0",
       "name": "Mac OS X",
       "family": "darwin",
       "version": "10.15.3",
       "platform": "darwin"
     },
     "name": "cyrille-laptop.home",
     "id": "04A12D9F-C409-5352-B238-99EA58CAC285",
     "architecture": "x86_64"
   }
}

Comparison between OpenTelemetry Semantic Conventions for logs and ECS

Principles

説明	OTelのログおよびイベントレコード	Elastic Common Schema（ECS）
アプリケーションインスタンスのすべてのログメッセージ／スパン／メトリクスで共有されるメタデータ	Resource Attributes	ECSフィールド
各ログメッセージ／スパン／メトリクスのデータポイントに固有のメタデータ	Attributes	ECSフィールド
ログイベントのメッセージ	Body	messageフィールド
命名規則	ドット区切りの名前	ドット区切りの名前
名前空間の再利用性	名前空間は合成されることを意図している	名前空間は合成されることを意図している
拡張性	属性は、既存の名前空間にユーザー定義のフィールドを追加するか、新しい名前空間を導入することで拡張できる	各名前空間に追加の属性を追加でき、ユーザーは独自の名前空間を作成できる

Data Types

カテゴリ	OTelのログおよびイベントレコード（GRPCのデータ型のすべてまたは一部）	ECSのデータ型
テキスト	string	text、match_only_text、keyword、constant_keyword、wildcard
日付	UNIXエポックからのナノ秒（uint64）	date、date_nanos
数値	number	long、double、scaled_float、boolean…
オブジェクト	uint32、uint64…	object（JSONオブジェクト）、flattened（単一のフィールド値としてのJSONオブジェクト全体）
構造化オブジェクト	現時点では複雑な意味的データ型は指定されていません（たとえば、OTelにはIPアドレス用の「ip」データ構造はなく、代わりに文字列が使用されています）。 OTelは配列とネストされたオブジェクトをサポートしていることに注意してください。	ip、geo_point、geo_shape、version、long_range、date_range、ip_range
バイナリデータ	バイト列	binary

Known Differences

OpenTelemetryセマンティック規約とECSの両方で定義されているフィールドには、いくつかの違いが存在します。この場合、重複するECSのフィールドを新しい仕様に統合しないことが理にかなっています。

OTelのログおよびイベントレコード	Elastic Common Schema（ECS）	説明
Timestamp（UNIXエポックからのナノ秒、uint64）	@timestamp（date）
TraceId（バイト列）、SpanId（バイト列）	trace.id（keyword）、span.id（keyword）
該当なし	Transaction.id（keyword）
SeverityText（string）	log.syslog.severity.name（keyword）、log.level（keyword）
SeverityNumber（number）	log.syslog.severity.code
Body（any）	message（match_only_text）
process.cpu.load（現時点では未指定だがOTel Collectorによって収集される） process.cpu.time（非同期カウンター） system.cpu.utilization	host.cpu.usage（scaled_float）はOTelのメトリクスが測定するものとはわずかに異なる測定方法です	ECSとOpenTelemetryの間では、ほとんどのメトリクスの名前とセマンティクスがわずかに異なることに注意してください

How would OpenTelemetry users practically use the new OpenTelemetry Semantic Conventions Attributes brought by ECS

ECSによって補強されたOpenTelemetryセマンティック規約の属性の具体的な使い方は、ユースケースとフィールドセットによって異なります。一般に、OpenTelemetryのユーザーは意識することなくECSへとアップグレードされ、新しいユースケースに対する属性の整合による恩恵を受けます。この作業の主な目標は、OpenTelemetryのシグナルの生成者（コレクター／エクスポーター）が、既存および新しいユースケースのために補強された統一シグナルを作成できるようにすることです。この統一性により、異なる生成者から発生したシグナル間の相関関係がより容易になります。その豊かさにより、根本原因分析、相関関係、レポーティングの選択肢が増えます。

ECSは多くの異なるユースケースとシナリオをカバーしていますが、以下では2つの例を概説します。

Example: OpenTelemetry Collector Receiver to collect the access logs of a web server

「Webサーバー XXX用のOTel Collectorアクセスログファイルレシーバー」の作成者は、OTelセマンティック規約の仕様の中に、Webサーバーのログのフィールドをマッピングするためのすべてのガイダンスを見出すでしょう。これには、OTelセマンティック規約が現在HTTP呼び出し向けに規定している属性だけでなく、User Agentや地理データのための属性も含まれます。

このマッピングの完全性は、統合の作成者が、他のWebコンポーネント（Webサーバー、ロードバランサー、L7ファイアウォールなど）のアクセスログと互換性のあるOTelログメッセージを生成する助けとなり、オブザーバビリティソリューションとのすぐに使える統合を可能にし、より豊かな相関関係を実現します。

Other Examples

Alternatives / Discussion

Prometheus Naming Conventions

Prometheusはオブザーバビリティメトリクスのデファクトスタンダードであり、OpenTelemetryはすでにPrometheusエコシステムとの完全な相互運用性を提供しています。

公式のPrometheusエクスポーター（たとえばNode／systemメトリクスエクスポーターやMySQLサーバーエクスポーター）によって収集されるメトリクスと、それに相当するOpenTelemetry Collectorのレシーバー（たとえばOTel CollectorのHost Metrics ReceiverやMySQL Receiver）との間で相互運用性を得ることは有用でしょう。

Prometheusのメトリクス命名規則における課題の一つは、これらが各統合の作成者によって定義された暗黙の規約であり、統合間の一貫性が欠けているために相関関係を実現できないことに注意してください。たとえば、この不一致は、エンドユーザーがアラートを設定・監視する際に対処しなければならない複雑さを増大させます。

Prometheusの規約はメトリクス名のスタイルに限定されており（Prometheusのメトリクスとラベルの命名を参照）、統一されたメトリクス名を規定するものではありません。

Other areas that need to be addressed by OTel (the project)

ECSがOTelに統合されるにあたり、長期的に対処が必要ないくつかの領域には、イノベーションプロセスの定義、ECSに対応するための変更をOTelの仕様に確実に組み込むこと、そして（もしあれば）破壊的変更を扱うプロセス（この点については提案「Define semantic conventions and instrumentation stability #2180」で取り組まれるべきです）が含まれます。また、既存の命名（たとえばPrometheusエクスポーター）を標準化された規約へ移行することも含まれます（システムメトリクスのセマンティック規約、OSプロセスメトリクスのセマンティック規約を参照）。