# Span Events APIの非推奨化

LLMS index: [llms.txt](/llms.txt)

---

OpenTelemetryはSpan Event APIを非推奨化します。
この記事では、この変更を行う理由、その概要、そして準備のために必要なことを説明します。
要約すると以下のとおりです。

- イベントを送信する2つの重複した方法（スパンイベントとログベースのイベント）によって生じる混乱と重複を解消したいと考えています。
- 新しいコードは、現在のスパンに関連付けられたログとしてイベントを記録すべきです。
- 古い「スパンイベント」スタイルは段階的に廃止されますが、スパン上のイベントを表示する既存のデータとビューは引き続き機能します。

## なぜSpan Event APIを非推奨にするのか？ {#why-deprecate-the-span-event-api}

現在、OpenTelemetryはトレースと相関するイベントを送信するための主要な方法を2つ提供しています。

- [Tracing API](/docs/specs/otel/trace/api)の`Span.AddEvent`または`Span.RecordException`メソッドを使用して作成されるスパンイベント。
- [Logs API](/docs/specs/otel/logs/api)を介して（直接、またはOpenTelemetryにブリッジされたロギングライブラリを通じて）送信され、アクティブなコンテキストに関連付けられるログベースのイベント。

同じ概念に対して競合する2つのAPIを持つことには、いくつかの欠点があります。

- **計装の作成者に対するガイダンスの分断。** ライブラリやフレームワークの作者は、非常に似たデータを送信するための2つの方法のいずれかを選択しなければなりません。
  選択が異なると、エコシステム全体でユーザーエクスペリエンスに一貫性がなくなります。
- **ユーザーにとっての重複した概念。** オペレーターはスパンイベントとログイベントの両方、それらのエクスポート方法、およびバックエンドでの扱いを理解しなければなりません。
- **進化の遅延。** イベントモデルの改善（たとえば、スキーマ、属性、後方互換性に関するもの）は、2か所で仕様策定と実装が必要になります。

OpenTelemetryコミュニティは、よりシンプルなメンタルモデルへの収束を進めています。
**イベントはLogs APIを介して送信される名前付きのログ**であり、スパン上の特別なケースとしてではなく、コンテキストを通じてトレースやメトリクスと相関するというモデルです。
この変更は、OpenTelemetryがイベントを表現する方法を統一するものとして重要です。
この方向性の背景については、以前のブログ記事[OpenTelemetry Logging and You](/blog/2025/opentelemetry-logging-and-you/)を参照してください。

同時に、スパンイベントが今日広く使用されていることも認識しています。
多くのバックエンドは専用のトレースビューでスパンイベントを表示しており、一部のユーザーは親スパンと同じOTLPエクスポートペイロードにイベントが含まれることに依存しています。

[OTEP 4430: Span Event API非推奨化計画][OTEP]のプランは、以下の目標のバランスを取ることを目指しています。

- 新しいイベントはLogs APIを通じて送信すべきという**明確で一貫したガイダンス**の提供。
- 互換性レイヤーを通じて、トレース内のスパンイベントに依存する**既存のワークフローの保持**。

つまり、スパンに付随するイベントを見る機能ではなく、スパンイベントを記録するための**API**を非推奨化するということです。

## 何が変わるのか？ {#what-is-changing}

非推奨化は**新しいイベントの記録方法**に焦点を当てています。

- ログベースのイベントに対するOTLPサポートはすでに安定しており、Logs APIはスパンイベントがこれまで持っていたすべてのものを、より豊富なメタデータとより柔軟なエクスポートおよびフィルタリング機能とともに記録できます。
- トレース仕様は、ログベースのイベントの送信を優先して`Span.AddEvent`や`Span.RecordException`などのAPIを非推奨化します。
- 言語APIとSDKはログベースのイベントをファーストクラスとして扱い、必要に応じてそれらのイベントをスパンイベントとして表示できる互換性オプションを提供します。
- 計装とセマンティック規約は、次のメジャーバージョンでスパンイベントからログベースのイベントへと段階的に移行しながら、それまでは既存の動作を安定した状態に保ちます。

## 何が変わらないのか？ {#what-stays-the-same}

Span Event APIが非推奨化されても、ユーザーエクスペリエンスのいくつかの重要な側面は意図的に保持されます。

- **シグナル間の相関は同じように機能し続けます。** ログベースのイベントは引き続きOpenTelemetryコンテキストに関連付けられます。
- **既存のデータは有効なままです。** すでにスパンイベントを使用しているデータは、サポートされているOTLPトレースモデルの一部として残ります。

非推奨化は、新しいコードでイベントを送信する単一の推奨方法を提供するものであり、スパン上のイベントへの可視性を削除するものではありません。

## 何をすべきか？ {#what-should-you-do}

まず何より、この移行が安全で段階的であり、現在依存しているワークフローと互換性があるものにしたいと考えています。

役割に応じて、今後の変更がどのように影響するか、そして何ができるかを以下に示します。

### オペレーター {#operators}

ダッシュボードや分析ツールでトレース、ログ、メトリクスを主に使用している場合は、以下のとおりです。

- すぐにアプリケーションやダッシュボードを変更する必要はありません。
- アップグレード時に、計装が例外やその他のイベントをスパンイベントではなくログベースのイベントとして送信するようになる場合があります。
  依存しているビュー（たとえば、スパンタイムラインやイベントビュー）でイベントが引き続き表示されることを確認してください。

### アプリケーション開発者 {#application-developers}

計装するアプリケーションを管理している場合は、以下のとおりです。

- すぐにコードを変更する必要はありません。
- 計装ライブラリの新しいバージョンはログベースのイベントの送信を開始する場合があるため、注意してください。
  ただし、スパンイベントの使用を継続するオプションが引き続き提供される場合があります。
- SDKは、ログベースのイベントをスパンイベントに変換する方法を提供します。

独自のカスタム計装を管理している場合は、以下のとおりです。

- 新しいイベントと例外にはLogs APIを優先してください。
- 特にすでに非推奨としてマークされているスパンイベントメソッドへの新しい依存関係の追加は避けてください。

### オブザーバビリティベンダー {#observability-vendors}

オブザーバビリティバックエンドまたはサービスを構築している場合は、以下のとおりです。

- ログベースのイベントの取り込みをサポートしてください。
- ユーザーが期待する既存のスパン指向のビューでログベースのイベントを引き続き表示できるようにしてください。

### 計装の作成者 {#instrumentation-authors}

OpenTelemetry計装を作成している場合は、以下のとおりです。

- 現在の安定したメジャーバージョンの動作互換性を当面維持してください。
- 現在のメジャーバージョンで、スパンイベントと並行してログベースのイベントを送信するオプトインメカニズム（[`OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN`](/docs/specs/semconv/exceptions)など）の追加を検討してください。
- 次のメジャーバージョンでは、新しいスパンイベントを追加するのではなく、更新されたセマンティック規約に従ってイベントと例外をLogs APIに移行する計画を立ててください。

### セマンティック規約の作成者 {#semantic-convention-authors}

OpenTelemetryセマンティック規約を定義または管理している場合は、以下のとおりです。

- イベントをログベースのイベントとして文書化し、スパンイベントではなくログレコードの属性（アトリビュート）とイベント名を指定してください。
- 現在スパンイベントに依存している既存の規約を発展させる際は、ログベースの同等物に関する明確なガイダンスを提供してください。

### OpenTelemetryメンテナー {#opentelemetry-maintainers}

OpenTelemetryの言語APIとSDKを管理している場合は、以下のとおりです。

- エンドユーザーが簡単にログベースのイベントを送信できるよう、Logs APIを公開して安定化させてください。
- ログベースのイベントを優先して`Span.AddEvent`や`Span.RecordException`などのスパンイベントメソッドの非推奨化に備えながら、必要に応じて互換性を維持してください。
- そのような表現に依存しているユーザーやバックエンド向けに、ログベースのイベントをスパンイベントに変換できるヘルパーや設定を提供してください。

## おわりに {#closing}

要件と懸念事項を[community#3312](https://github.com/open-telemetry/community/issues/3312)で共有してください。
特に、どの互換性の側面が最も重要かに関心があります。
たとえば、トレースビューでスパンに直接表示されるイベントに依存しているか、親スパンと同じOTLPエクスポートペイロードにイベントが含まれることに依存しているか、または現在のツールが依存している他の動作があるかなどです。

ここでの非推奨化は、スパンイベントを**削除する**ことを意味するものでは**ありません**。
新しいイベントを送信する推奨方法をLogs APIへとシフトさせることです。

私たちの目標は、OpenTelemetryのイベントをより**シンプルで、より一貫性があり、より強力**なものにしながら、新しい推奨事項への円滑な移行を提供することです。

[OTEP]: https://github.com/open-telemetry/opentelemetry-specification/blob/fd43145dde7e5192ebc59a20992d98a3e6af5553/oteps/4430-span-event-api-deprecation-plan.md