otel-span-events-to-logs-migration

Span Event 迁移到日志

使用此技能，将检测从 Span Event API（AddEvent、RecordException 及各语言中的对应方法）迁移到 Logs API，并遵循已接受的 OTEP 4430 弃用计划。

背景

OpenTelemetry 项目已接受一项计划，弃用 Span.AddEvent 和 Span.RecordException，改为通过 Logs API 发出事件和异常。Span Event 这一概念仍然有效——可以通过与当前 Span 关联的日志发出，也可以选择将其桥接回 Span proto。

截至 2026-10-25 的状态（规范 v1.62.0）：OTEP 4430 已获接受，基于日志的事件／异常发出方式已在 Logs API 中规范化，SDK 的“事件到 Span Event 桥接”已规范化，状态为 Development。规范尚未正式将 Trace API 的 AddEvent／RecordException 方法标记为 Deprecated——这一步仍待完成。请将现有的 Span Event 调用视为迁移候选项，而不是自动判定为无效代码；某些 SDK 特定的对应方法状态已经变更（例如，OpenTelemetry .NET 的 Activity.RecordException 扩展已标记为 [Obsolete]，建议改用 Activity.AddException，后者仍属于 Span Event API）。

完整背景请参阅 references/deprecation-plan.md。

工作流

0. 迁移前做好准备。

• 检查项目的 OpenTelemetry SDK 版本是否支持基于日志的事件（如果有，请查看 otel-sdk-versions 技能的版本索引）
• 确认项目是否已配置 LoggerProvider；如果没有，必须进行配置
• 确定下游使用方（后端、仪表板、告警）是否依赖于 span 原型封装中出现的 span 事件

1. 扫描代码库，查找 span 事件的用法。

• 搜索 AddEvent、add_event、addEvent、RecordException、record_exception、recordException、RecordError、record_error、AddException 及特定语言的变体
• 对每个调用点进行分类：一般事件、异常记录或信息性注释
• 记录每个调用点使用的 span 上下文、属性和时间戳

2. 根据决策树对每个调用点进行分类。

• 完整分类逻辑请参阅 references/decision-tree.md
• 三种处理结果为：迁移为基于日志的事件、转换为 span 属性或移除

3. 对每个调用点应用迁移。

• 各语言的迁移前后模式请参阅 references/migration-patterns.md
• 确保替换后的日志记录包含正确的 span 上下文、事件名称、属性和时间戳；对于异常，使用适用的语义约定事件名称（通常是特定操作的 .exception 名称），仅在通用处理程序中使用 exception
• 在 Go（1.47.0+，Logs API/SDK 已稳定）中，使用根 go.opentelemetry.io/otel 包中的 otel.Logger 获取 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：请使用 attribute.String(...)，而不是 log.String(...)；使用 Record.SetEventName(...) 设置事件名称
• 对于异常，保留适用的 semconv 属性：exception.type 和 exception.message（至少需要其中一项）；如果语言或错误类型允许且有意义，再加上 exception.stacktrace（在 Go 中，除非错误库能够保留源堆栈，否则请省略它——不要在发出日志时调用 runtime.Stack）

4. 如果需要向后兼容，请配置 SDK 桥接器。

• 请参阅 references/backward-compat.md
• 这是一个 SDK 级别的日志处理器，可将基于日志的事件转换回 span 事件
• 仅当下游系统要求 span 事件与 span 位于同一原型封装中时才需要

5. 验证迁移。

必须完成的检查循环

每次都要遵循此循环：

1. 扫描并分类所有 span 事件调用点
2. 根据决策树和模式迁移每个调用点
3. 根据下面的检查清单审查已更改的代码
4. 重新打开已更改的文件，并以代码库中的证据确认每项检查清单内容
5. 如果有任何项目尚未解决，则修补代码，或说明原因并标记为不适用，然后重复审查
6. 所有检查清单项目均已完成或明确标记为不适用后，才能结束

不能仅凭意图将检查清单项目标记为已完成。只有在当前代码库中确认后，才能将其标记为已完成。

迁移检查清单

对于每个项目，请在最终答复中报告以下状态之一：

• [x] 已完成
• [~] 不适用，并说明原因
• [ ] 尚未解决

每个已完成项目都要附上文件引用作为证据。

• [ ] 已识别并分类所有通用 span 事件调用点，包括 AddEvent / add_event / addEvent，以及 .NET ActivityEvent 等语言等价项。
• [ ] 已识别并分类所有异常 span 事件调用点，包括 RecordException / record_exception / recordException，以及 Go RecordError、Rust record_error 和 .NET AddException 等语言等价项。
• [ ] 已在 SDK 设置中配置 LoggerProvider（或该配置已存在）。
• [ ] 每个迁移后的事件都使用 Logs API，并包含正确的事件名称和属性。
• [ ] 每个迁移后的异常都保留适用的 semconv 属性：exception.type 和 exception.message（至少需要其中一项），并在语言或错误类型使其有意义时保留 exception.stacktrace。
• [ ] 迁移后的日志记录包含活动 span 的上下文，以便进行 trace 关联。
• [ ] 被分类为“转换为 span 属性”的调用点现已改用 span 属性。
• [ ] 被分类为“移除”的调用点已移除，并附有理由。
• [ ] 如果下游系统需要在 span 封套中保留 span 事件，则已配置向后兼容桥接。
• [ ] 没有意外遗留的 span 事件 API 调用点；任何保留的 AddEvent / RecordException / RecordError / AddException / ActivityEvent / 等价调用，都有当前版本兼容性的合理依据。
• [ ] 实现后已重新阅读更改过的文件，以验证最终状态。
• [ ] 最终答复包含此检查清单、文件证据，以及任何剩余风险或缺口。

最终审核格式

在最终答复中，按以下格式包含检查清单：

• [x] 已配置 LoggerProvider。证据：src/telemetry/setup.go:42 -- 添加了带批处理处理器的 OTLP 日志导出器。
• [~] 向后兼容桥接。原因：没有下游系统依赖 proto 封套中的 span 事件。
• [ ] 异常迁移。缺少证据；需要重新检查。