Yoshi Yamaguchi

OTEP-0265: イベントの基本

動機

イベントの導入は物議を醸してきたため、いくつかの基本事項を文書化し、合意しておきたいと考えています。

OpenTelemetryのイベントとは

OpenTelemetryのイベントは、イベント名を必要とし、そのイベント名によって示される特定の構造に従う、OpenTelemetryのログの一種です。 これらはOpenTelemetryのセマンティック規約における中核的な概念です。

OTLP

OpenTelemetryのイベントはOpenTelemetryのログの一種であるため、同じOTLPログのデータ構造とパイプラインを共有します。

API

OpenTelemetryは、OpenTelemetryのイベントを発行する機能を含む（ユーザー向けの）Logs APIを提供すべきです（SHOULD）。

他のロギングライブラリとの相互運用性

OpenTelemetryは、OpenTelemetryのLogs APIから他のロギングライブラリ（Log4jなど）へOpenTelemetryのログを送信する方法を提供すべきです（SHOULD）。 これにより、ユーザーは既存の（OpenTelemetryではない）ログストリームにOpenTelemetryのログを統合できます。

OpenTelemetryは、そのライブラリにその機能があれば、OpenTelemetryのLogs APIを完全にバイパスして、既存の言語固有のロギングライブラリを介して直接OpenTelemetryのログ（イベントを含む）を発行する方法を提供すべきです（SHOULD）。

OpenTelemetryは、計装ライブラリに対して、他のロギングライブラリを使ってOpenTelemetryのイベントを発行するのではなく、OpenTelemetryのLogs APIを使ってOpenTelemetryのイベントを発行することを推奨します。 この推奨事項は、複数のアプローチが混在することを避け、ユーザーにシンプルで一貫したオンボーディング体験を提供することを目的としています。

OpenTelemetryはまた、アプリケーション開発者に対しても、他のロギングライブラリを使う代わりにOpenTelemetryのLogs APIを使ってOpenTelemetryのイベントを発行することを推奨します。 これは、イベント名を持たない、あるいは構造化されていないログを誤って発行してしまうことを防ぐのに役立つためです。

他のロギングライブラリを使うのではなく、OpenTelemetryのイベントの発行にOpenTelemetryのLogs APIを推奨することは、OpenTelemetryのAPI全体像をより明確にすることに貢献します。 これにより、トレース、メトリクス、イベントのそれぞれに対して、ネイティブな計装での直接利用に適したファーストクラスのユーザー向けAPIを持つという、統一されたアプローチが保証されます。

スパンイベントとの関係

イベントは、長期的にはスパンイベントを置き換えることを意図しています。 スパンイベントは、ユーザーがイベントを優先して使うべきであることを示すために非推奨となります。

詳細については、OTEP 4430: スパンイベントAPIの非推奨化計画を参照してください。

SDK

これは、既存のOpenTelemetry Logs SDKを指します。

代替案

過去2年以上にわたり、多くの代替案が検討されてきました。

これらの代替案は、主に命名（そもそもEventという単語を使うべきかなど）と構成（Event APIをLogs APIとは別のものにすべきかなど）の違いに帰着します。

このOTEPの現状は、サポートされている幅広い言語エコシステム全体において、もっとも多くのユーザーにとってもっとも混乱の少ない選択肢であると私たちが考えるものを表しています。

未解決の問題

  • Logs APIから言語固有のロギングライブラリへログをルーティングすると同時に、言語固有のロギングライブラリからOpenTelemetryのLogging Exporterへログをルーティングすることを、どのようにサポートするか。
  • ログのbodyは他のロギングライブラリとどのように相互運用するか。 OpenTelemetryのログには構造を格納する場所が2つ（attributesとbody）ある一方で、多くのロギングライブラリには構造の階層が1つしかないため、この場合に両者の間で双方向のマッピングをどう行うかは自明ではありません。
  • イベントのbodyはスパンイベントとどのように相互運用するか。
  • Logs APIは、重大度レベルとイベント名にもとづく Enabled 関数を持つべきか。
  • OpenTelemetryのLogs APIがユーザー向けになった今、どのような機能を持つべきか （ブラウザや、場合によっては他のクライアント環境のバンドルサイズの制約を念頭に置きつつ）。
  • OpenTelemetryのLogs APIがユーザー向けになった今、どのような使い勝手の改善が理にかなっているか （ブラウザや、場合によっては他のクライアント環境のバンドルサイズの制約を念頭に置きつつ）。
  • OpenTelemetryのイベントは、生のメトリクスイベントとどのように関係するか （例：opentelemetry-specification/617）。
  • OpenTelemetryのイベントは、生のスパンイベントとどのように関係するか（例：ストリーミングSDK）。
  • イベント名は属性として取得すべきか、それともトップレベルのフィールドとして取得すべきか。
  • サンプリングが存在する場合、イベントとスパンイベントの相互運用性はどのように機能するか （スパンイベントはスパンと一緒にサンプリングされるため）。