Yoshi Yamaguchi

OTEP-4430: スパンイベントAPI非推奨化計画

動機

OTEP 265: Event Vision では、スパンイベントを（ログベースの）イベントに置き換える形で非推奨化する意図が述べられています。

その後の議論を経て、スパンイベントAPIのみを非推奨化し、Logs APIを介してスパンイベントを発行する能力は維持する計画としています。

これにより、非推奨化の主目的、すなわちイベントを発行する際にはLogs APIを使用するという単一の一貫したガイダンスを計装作成者に提供するという目的を達成しつつ、スパンイベントが自身を含むスパンと同一のprotoエンベロープ内で発行されることに依存するユースケースもサポートし続けることができます。

計画

protoにおいて

（ログベースの）イベントを安定化します。

仕様書において

  1. Logs APIを介した例外・イベントの発行を安定化します。

    これにより、例外やイベントをスパンイベントAPIで記録する代わりに、Logs APIを使って記録できるようになります。

    注記: Logs APIを介した例外の発行はすでに安定していますが、対処すべき未解決の疑問がいくつかあります。

    • RecordExceptionに類似した、Logsに対する何らかの便利な関数を規定したいか。
    • ログベースの例外に対して、イベント名フィールドに関して何か特定の推奨事項を設けたいか。

  2. Span RecordException をDeprecatedとしてマークし、代わりにLogs APIを使って例外を記録することを推奨します。

  3. Span AddEvent をDeprecatedとしてマークし、代わりにLogs APIを使ってイベントを記録することを推奨します。

    これは2と並行して実施できます。

各APIおよびSDKにおいて

  1. Logs APIを介した例外・イベントの発行を実装・安定化します。

  2. SDKベースの後方互換性の仕組みを実装します。

  3. Span RecordException をDeprecatedとしてマークし、代わりにLogs APIを使って例外を記録することを推奨します。

  4. Span AddEvent をDeprecatedとしてマークし、代わりにLogs APIを使ってイベントを記録することを推奨します。

    これは3と並行して実施できます。

各計装において

Span RecordException およびSpan AddEvent を使用している安定した計装については、以下のとおりとします。

  • 当該計装の現在のメジャーバージョンにおいて
    • これらの使用を継続してよい(SHOULD)。
  • 当該計装の次のメジャーバージョンにおいて
    • これらの使用を停止し、代わりにLogs APIを使って例外・イベントを記録するべきです(SHOULD)。
    • ユーザーは、(ログベースの)例外・イベントをスパンイベントとして送信するをオプトインすることで、従来のテレメトリー出力を維持できます。
    • 計装がスパンに関する追加の詳細（タイムスタンプを必要としない詳細）を記録するためにスパンイベントを以前使用していた場合、代わりにこれらの詳細をスパンの属性として記録するべきです(SHOULD)。 この件の詳細については、semantic-conventions#2010 および opentelemetry-specification#4446 を参照してください。

安定していない計装は、上記のガイダンスに従うかどうかについて最善の判断を用いるべきです(SHOULD)。

(ログベースの)例外・イベントをスパンイベントとして送信する

SDKを介して

スパンイベントが自身を含むスパンと同一のprotoエンベロープ内で発行されることに依存するユースケースのため、また新しい計装への更新時に従来の動作を維持する必要があるユーザーのために、(ログベースの)例外・イベントをスパンイベントとして送信する方法が存在しなければなりません(MUST)。

このメカニズムは、以下のように実装されるべきです(SHOULD)（プロトタイプを参照）。

  • 例外・イベントレコードをスパンイベントに変換し、現在のスパンにアタッチするSDKベースのログプロセッサーであり、その動作と設定はOpenTelemetry仕様書で定義されます。
  • （パッケージがインストールされていることを前提として）このログプロセッサーを宣言的な設定を介して追加する標準的な方法。

ユーザーは、例外・イベントレコードをログとしてもエクスポートしたいかどうかに応じて、バッチログレコードプロセッサーとログエクスポーターを追加できます。

このログプロセッサーは、標準のOpenTelemetryゼロコードディストリビューション（その言語向けに存在する場合）に含まれるべきです(SHOULD)。

Collectorを介して

注記: これはあくまであると望ましいものであり、スパンイベントAPI非推奨化計画の他のいかなる部分にも必須ではありません。

このメカニズムは、以下のように実装されてもよいです(MAY)。

  • スパンをバッファリングし、(ログベースの)イベントを適切なスパンに移動するCollectorベースのプロセッサー。

このログプロセッサーは、標準のOpenTelemetry Collector Contribディストリビューションに含まれてもよいです(MAY)。

コミュニケーション計画

このOTEPが受理された場合、読者がフィードバックを提供できる手段（たとえば、フィードバックを収集している仕様書のイシューを示すなど）を添えたブログ記事を公開します。 このブログ記事には、スパンイベントAPIを非推奨化するという決定の根拠を含めるべきです。