otel-span-events-to-logs-migration

Span Events から Logs への移行

採用済みの OTEP 4430 の非推奨化計画に従って、Span Event API（AddEvent、RecordException および各言語での同等の API）から Logs API へ計装を移行します。

背景

OpenTelemetry プロジェクトは、Span.AddEvent と Span.RecordException を非推奨とし、Logs API を通じてイベントや例外を出力する計画を採用しました。Span Events という概念自体は引き続き有効です。アクティブなスパンに関連付けられたログを通じて出力でき、必要に応じてスパンの proto にブリッジバックすることもできます。

2026-10-25 時点（仕様 v1.62.0）では、OTEP 4430 は採用済みで、ログベースのイベント／例外出力は Logs API で規定されており、SDK の「イベントから Span Event へのブリッジ」は Development ステータスで規定されています。仕様では、トレース API のメソッド AddEvent／RecordException はまだ正式に Deprecated とされていません。この手順は引き続き保留中です。既存の Span Event 呼び出しは、無効なコードとみなすのではなく、移行候補として扱ってください。一部の SDK 固有の同等機能では、すでにステータスが変更されています（たとえば、OpenTelemetry .NET の Activity.RecordException 拡張メソッドは、引き続き Span Event API である Activity.AddException を推奨する形で [Obsolete] になっています）。

詳細については、references/deprecation-plan.md を参照してください。

ワークフロー

0. 移行前に準備します。

• プロジェクトの OpenTelemetry SDK バージョンがログベースのイベントに対応しているか確認します（利用可能な場合は、otel-sdk-versions スキルのバージョンインデックスを確認してください）。
• プロジェクトで LoggerProvider が設定されているか確認します。設定されていない場合は、設定する必要があります。
• 下流のコンシューマー（バックエンド、ダッシュボード、アラート）が、スパンのプロトコルバッファーエンベロープ内にスパンイベントが含まれることに依存しているか確認します。

1. コードベース内のスパンイベントの使用箇所を検索します。

• AddEvent、add_event、addEvent、RecordException、record_exception、recordException、RecordError、record_error、AddException、および言語固有のバリエーションを検索します。
• 各呼び出し箇所を、一般的なイベント、例外の記録、情報アノテーションのいずれかに分類します。
• 各箇所でのスパンコンテキスト、属性、タイムスタンプの使用状況を記録します。

2. 判定ツリーを使って各呼び出し箇所を分類します。

• 分類ロジックの全容については、references/decision-tree.md を参照してください。
• 結果は、ログベースのイベントへの移行、スパン属性への変換、削除の3つです。

3. 各呼び出し箇所に移行を適用します。

• 言語ごとの移行前後のパターンについては、references/migration-patterns.md を参照してください。
• 置き換え後のログレコードに、正しいスパンコンテキスト、イベント名、属性、タイムスタンプが設定されていることを確認します。例外には該当するセマンティック規約のイベント名（通常は操作固有の .exception 名）を使用し、汎用ハンドラーでは exception を使用します。
• Go（1.47.0 以降、Logs API/SDK は安定版）では、ルートの go.opentelemetry.io/otel パッケージの otel.Logger でロガーを取得します（otel/log/global は非推奨です）。
• Java では、contrib の io.opentelemetry.contrib.eventbridge.EventToSpanEventBridge は opentelemetry-java-contrib v1.60.0 で削除されました。opentelemetry-sdk-extension-incubator の io.opentelemetry.sdk.extension.incubator.logs.EventToSpanEventBridge を使用してください（references/backward-compat.md を参照）。
• Go では、log.Record.AddAttributes は attribute.KeyValue を受け取ります。log.String(...) ではなく attribute.String(...) を使用し、Record.SetEventName(...) でイベント名を設定します。
• 例外では、該当する semconv 属性を保持します。exception.type と exception.message の少なくとも一方が必須で、言語やエラー型にとって意味がある場合は exception.stacktrace も保持します（Go では、エラーライブラリが発生元のスタックを保持している場合を除き、省略してください。出力箇所で runtime.Stack を呼び出さないでください）。

4. 下位互換性が必要な場合は、SDK ブリッジを設定します。

• references/backward-compat.md を参照してください。
• これは、ログベースのイベントをスパンイベントに戻す SDK レベルのログプロセッサーです。
• 下流システムが、スパンと同じプロトコルバッファーエンベロープ内にスパンイベントを必要とする場合にのみ必要です。

5. 移行を検証します。

必須の完了ループ

毎回、次のループに従ってください。

1. すべてのスパンイベントの呼び出し箇所を検索して分類します。
2. 判定ツリーとパターンに従って、各呼び出し箇所を移行します。
3. 変更したコードを以下のチェックリストに照らしてレビューします。
4. 変更したファイルを再度開き、コードベース内の根拠を確認しながら、チェックリストの各項目を検証します。
5. 未解決の項目があれば、コードを修正するか、理由を添えて該当なしとし、その後レビューを繰り返します。
6. チェックリストの全項目が完了するか、明示的に該当なしとされるまで、作業を終えないでください。

意図だけを根拠にチェックリストの項目を完了扱いにしないでください。現在のコードベースで確認した後にのみ、完了扱いにしてください。

移行チェックリスト

各項目について、最終回答で次のいずれかのステータスを報告してください。

• [x] 完了
• [~] 該当なし。理由を記載
• [ ] 未解決

完了した各項目について、証拠としてファイル参照を記載してください。

• [ ] AddEvent／add_event／addEvent および .NET の ActivityEvent などの言語固有の同等機能を含め、一般的なスパンイベントの呼び出し箇所をすべて特定し、分類している。
• [ ] RecordException／record_exception／recordException および Go の RecordError、Rust の record_error、.NET の AddException などの言語固有の同等機能を含め、例外スパンイベントの呼び出し箇所をすべて特定し、分類している。
• [ ] SDK のセットアップで LoggerProvider を設定している（または、すでに設定されていた）。
• [ ] 移行した各イベントで、正しいイベント名と属性を使用して Logs API を呼び出している。
• [ ] 移行した各例外で、該当する semconv 属性を保持している。exception.type と exception.message は少なくとも一方が必須で、言語やエラー型に応じて意味がある場合は exception.stacktrace も保持している。
• [ ] 移行したログレコードに、トレース相関用のアクティブなスパンコンテキストが含まれている。
• [ ] 「スパン属性に変換」と分類した呼び出し箇所で、代わりにスパン属性を使用している。
• [ ] 「削除」と分類した呼び出し箇所を、理由を示したうえで削除している。
• [ ] 下流システムがスパンエンベロープ内のスパンイベントを必要とする場合、下位互換性ブリッジを設定している。
• [ ] 意図せず残っているスパンイベント API の呼び出し箇所がない。残している AddEvent／RecordException／RecordError／AddException／ActivityEvent／同等機能があれば、現行バージョンとの互換性のために必要な理由を示している。
• [ ] 変更したファイルを実装後に再読し、最終状態を確認している。
• [ ] 最終回答に、このチェックリスト、ファイルの証拠、残っているリスクや不足事項を含めている。

最終レビューの形式

最終回答には、次の形式でチェックリストを含めてください。

• [x] LoggerProvider を設定済み。証拠：src/telemetry/setup.go:42 -- バッチプロセッサー付きの OTLP ログエクスポーターを追加。
• [~] 下位互換性ブリッジ。理由：下流システムは proto エンベロープ内のスパンイベントに依存していない。
• [ ] 例外の移行。証拠なし。再確認が必要。