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


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

## 動機 {#motivation}

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

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

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

## 計画 {#the-plan}

### protoにおいて {#in-the-proto}

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

### 仕様書において {#in-the-specification}

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

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

   注記: Logs APIを介した例外の発行は[すでに安定しています](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-logs.md#semantic-conventions-for-exceptions-in-logs)が、対処すべき未解決の疑問がいくつかあります。

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

2. [Span RecordException](../specification/trace/api.md#record-exception) を[Deprecated](../specification/document-status.md#maturity-levels)としてマークし、代わりにLogs APIを使って例外を記録することを推奨します。

3. [Span AddEvent](../specification/trace/api.md#add-events) を[Deprecated](../specification/document-status.md#maturity-levels)としてマークし、代わりにLogs APIを使ってイベントを記録することを推奨します。

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

### 各APIおよびSDKにおいて {#per-api-and-sdk}

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

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

   - [(ログベースの)例外・イベントをスパンイベントとして送信する](#via-the-sdk)

3. [Span RecordException](../specification/trace/api.md#record-exception) を[Deprecated](../specification/document-status.md#maturity-levels)としてマークし、代わりにLogs APIを使って例外を記録することを推奨します。

4. [Span AddEvent](../specification/trace/api.md#add-events) を[Deprecated](../specification/document-status.md#maturity-levels)としてマークし、代わりにLogs APIを使ってイベントを記録することを推奨します。

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

### 各計装において {#per-instrumentation}

[Span RecordException](../specification/trace/api.md#record-exception) および[Span AddEvent](../specification/trace/api.md#add-events) を使用している[安定した](../specification/versioning-and-stability.md#stable)計装については、以下のとおりとします。

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

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

## (ログベースの)例外・イベントをスパンイベントとして送信する {#sending-log-based-exceptions-and-events-as-span-events}

### SDKを介して {#via-the-sdk}

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

このメカニズムは、以下のように実装されるべきです(SHOULD)（[プロトタイプ](https://github.com/open-telemetry/opentelemetry-java-contrib/blob/80adbe1cf8de647afa32c68f921aef2bbd4dfd71/processors/README.md#event-to-spanevent-bridge)を参照）。

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

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

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

### Collectorを介して {#via-the-collector}

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

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

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

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

## コミュニケーション計画 {#communication-plan}

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