otel-span-events-to-logs-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Span Events to Logs Migration

Span Events 到 Logs 的迁移

Use this skill to migrate instrumentation from the Span Event API (

AddEvent

RecordException

, and language equivalents) to the Logs API, following the accepted OTEP 4430 deprecation plan.

使用本skill将工具从Span Event API（

AddEvent

、

RecordException

及各语言等效方法）迁移至Logs API，遵循已通过的OTEP 4430弃用计划。

Background

背景

The OpenTelemetry project accepted a plan to deprecate

Span.AddEvent

and

Span.RecordException

in favor of emitting events and exceptions through the Logs API. Span Events as a concept remain valid -- they can be emitted via logs that correlate to the active span, and optionally bridged back into the span proto.

Status as of 2026-08-13: OTEP 4430 is accepted, log-based event/exception emission is specified in the Logs API, and the SDK "event to span event bridge" is specified with Development status. The trace API methods

AddEvent

RecordException

are not yet formally marked Deprecated in the specification -- that step is still pending. Treat existing span-event calls as migration candidates, not automatically invalid code; some SDK-specific equivalents have already changed status (for example OpenTelemetry .NET's

Activity.RecordException

extension is

[Obsolete]

in favor of

Activity.AddException

, which is still a span-event API).

See

references/deprecation-plan.md

for the full context.

OpenTelemetry项目已通过一项计划，弃用

Span.AddEvent

和

Span.RecordException

，转而通过Logs API发送事件和异常。Span Events作为概念仍然有效——它们可以通过与活动span关联的日志发送，并且可选择性地桥接回span proto中。

截至2026年8月13日的状态：OTEP 4430已通过，基于日志的事件/异常发送已在Logs API中明确规定，SDK的“事件到span事件桥接器”处于开发状态规范阶段。追踪API方法

AddEvent

RecordException

尚未在规范中正式标记为已弃用——这一步仍在等待中。将现有的span-event调用视为迁移候选对象，而非自动无效的代码；部分SDK特定的等效方法已更改状态（例如OpenTelemetry .NET的

Activity.RecordException

扩展已标记为

[Obsolete]

，转而使用

Activity.AddException

，但这仍然是span-event API）。

查看

references/deprecation-plan.md

获取完整背景信息。

Workflow

工作流程

Prepare before migrating.

check the project's OpenTelemetry SDK version supports log-based events (check the
```
manual-instrumentation
```
skill's version index if available)
identify whether the project has a LoggerProvider configured; if not, one must be set up
determine if downstream consumers (backends, dashboards, alerts) depend on span events appearing in the span proto envelope

Scan the codebase for span event usage.

search for

AddEvent

add_event

addEvent

RecordException

record_exception

recordException

RecordError

AddException

, and language-specific variants

categorize each call site: general event, exception recording, or informational annotation
note the span context, attributes, and timestamp usage at each site

Classify each call site using the decision tree.

see
```
references/decision-tree.md
```
for the full classification logic
the three outcomes are: migrate to log-based event, convert to span attributes, or remove

Apply the migration for each call site.

see
```
references/migration-patterns.md
```
for language-specific before/after patterns
ensure the replacement log record carries the correct span context, event name, attributes, and timestamp; for exceptions use the applicable semantic-convention event name (normally an operation-specific
```
.exception
```
name), reserving
```
exception
```
for generic handlers
for exceptions, preserve the applicable semconv attributes:
```
exception.type
```
and
```
exception.message
```
(at least one is required), plus
```
exception.stacktrace
```
when the language/error type makes it meaningful (in Go, omit it unless an error library preserves the origin stack -- do not call
```
runtime.Stack
```
at the emit site)

If backward compatibility is needed, configure the SDK bridge.

see
```
references/backward-compat.md
```
this is an SDK-level log processor that converts log-based events back to span events
only needed when downstream systems require span events in the same proto envelope as the span

Verify the migration.

迁移前准备。

检查项目的OpenTelemetry SDK版本是否支持基于日志的事件（若有可用的
```
manual-instrumentation
```
skill版本索引，可参考该索引）
确认项目是否已配置LoggerProvider；若未配置，则必须设置一个
判断下游消费者（后端、仪表盘、告警）是否依赖出现在span proto包中的span events

扫描代码库中span event的使用情况。

搜索

AddEvent

、

add_event

、

addEvent

、

RecordException

、

record_exception

、

recordException

、

RecordError

、

AddException

及各语言特定变体

对每个调用点进行分类：通用事件、异常记录或信息注释
记录每个调用点的span上下文、属性和时间戳使用情况

使用决策树对每个调用点进行分类。

查看
```
references/decision-tree.md
```
获取完整分类逻辑
三种结果为：迁移到基于日志的事件、转换为span属性或移除

对每个调用点应用迁移。

查看
```
references/migration-patterns.md
```
获取各语言特定的迁移前后示例
确保替换后的日志记录携带正确的span上下文、事件名称、属性和时间戳；对于异常，使用适用的语义规范事件名称（通常为特定操作的
```
.exception
```
名称），将
```
exception
```
保留给通用处理器使用
对于异常，保留适用的语义规范属性：
```
exception.type
```
和
```
exception.message
```
（至少需要其中一个），当语言/错误类型有意义时还需保留
```
exception.stacktrace
```
（在Go语言中，除非错误库保留了原始栈信息，否则省略该属性——不要在发送站点调用
```
runtime.Stack
```
）

若需要向后兼容，配置SDK桥接器。

查看
```
references/backward-compat.md
```
这是一个SDK级别的日志处理器，可将基于日志的事件转换回span events
仅当下游系统要求span events与span处于同一个proto包中时才需要配置

验证迁移结果。

Required Completion Loop

必需的完成循环

Follow this loop every time:

scan and classify all span event call sites
migrate each call site following the decision tree and patterns
review the changed code against the checklist below
re-open the changed files and confirm each checklist item with codebase evidence
if any item is unresolved, patch the code or mark it not applicable with a reason, then repeat the review
do not finish until every checklist item is completed or explicitly marked not applicable

Do not mark a checklist item complete based on intent alone. Mark it complete only after confirming it in the current codebase.

每次迁移都需遵循以下循环：

扫描并分类所有span event调用点
根据决策树和示例迁移每个调用点
根据下方清单审查修改后的代码
重新打开修改后的文件，用代码库中的证据确认每个清单项
若有任何未解决的项，修改代码或标记为不适用并说明原因，然后重复审查
直到每个清单项都完成或明确标记为不适用后，才能结束

不要仅根据意图标记清单项为完成。只有在当前代码库中确认后，才能标记为完成。

Migration Checklist

迁移清单

For every item, report one of these statuses in the final answer:

```
[x]
```
completed
```
[~]
```
not applicable, with a reason
```
[ ]
```
unresolved

Include file references as evidence for every completed item.

```
[ ]
```
All general span-event call sites identified and classified, including
```
AddEvent
```
/
```
add_event
```
/
```
addEvent
```
and language equivalents such as .NET
```
ActivityEvent
```
.
```
[ ]
```
All exception span-event call sites identified and classified, including
```
RecordException
```
/
```
record_exception
```
/
```
recordException
```
and language equivalents such as Go
```
RecordError
```
, Rust
```
record_error
```
, and .NET
```
AddException
```
.
```
[ ]
```
A LoggerProvider is configured in the SDK setup (or already existed).
```
[ ]
```
Each migrated event uses the Logs API with the correct event name and attributes.
```
[ ]
```
Each migrated exception preserves the applicable semconv attributes:
```
exception.type
```
and
```
exception.message
```
(at least one is required), plus
```
exception.stacktrace
```
when the language/error type makes it meaningful.
```
[ ]
```
Migrated log records carry the active span context for trace correlation.
```
[ ]
```
Call sites classified as "convert to span attributes" now use span attributes instead.
```
[ ]
```
Call sites classified as "remove" have been removed with justification.
```
[ ]
```
Backward compatibility bridge is configured if downstream systems require span events in the span envelope.
```
[ ]
```
No remaining span-event API call sites are left unintentionally; any retained
```
AddEvent
```
/
```
RecordException
```
/
```
RecordError
```
/
```
AddException
```
/
```
ActivityEvent
```
/ equivalent call is justified for current-version compatibility.
```
[ ]
```
The changed files were re-read after implementation to verify the final state.
```
[ ]
```
The final answer includes this checklist, file evidence, and any remaining risks or gaps.

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

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

为每个已完成的项提供文件引用作为证据。

```
[ ]
```
已识别并分类所有通用span-event调用点，包括
```
AddEvent
```
/
```
add_event
```
/
```
addEvent
```
及各语言等效方法（如.NET
```
ActivityEvent
```
）。
```
[ ]
```
已识别并分类所有异常span-event调用点，包括
```
RecordException
```
/
```
record_exception
```
/
```
recordException
```
及各语言等效方法（如Go
```
RecordError
```
、Rust
```
record_error
```
和.NET
```
AddException
```
）。
```
[ ]
```
SDK设置中已配置LoggerProvider（或已存在）。
```
[ ]
```
每个迁移后的事件都使用Logs API，并带有正确的事件名称和属性。
```
[ ]
```
每个迁移后的异常都保留了适用的语义规范属性：
```
exception.type
```
和
```
exception.message
```
（至少需要其中一个），当语言/错误类型有意义时还保留了
```
exception.stacktrace
```
。
```
[ ]
```
迁移后的日志记录携带活动span上下文以实现追踪关联。
```
[ ]
```
被分类为“转换为span属性”的调用点现在已使用span属性替代。
```
[ ]
```
被分类为“移除”的调用点已被移除并说明理由。
```
[ ]
```
若下游系统要求span events在span包中，已配置向后兼容桥接器。
```
[ ]
```
无意外遗留的span-event API调用点；任何保留的
```
AddEvent
```
/
```
RecordException
```
/
```
RecordError
```
/
```
AddException
```
/
```
ActivityEvent
```
/ 等效调用都已针对当前版本兼容性进行了合理说明。
```
[ ]
```
实现后重新读取修改后的文件以验证最终状态。
```
[ ]
```
最终答案包含本清单、文件证据及任何剩余风险或差距。

Final Review Format

最终审查格式

In the final answer, include the checklist in this format:

```
[x]
```
LoggerProvider configured. Evidence:
```
src/telemetry/setup.go:42
```
-- added OTLP log exporter with batch processor.
```
[~]
```
Backward compatibility bridge. Reason: no downstream systems depend on span events in the proto envelope.
```
[ ]
```
Exception migration. Missing evidence; re-check required.

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

```
[x]
```
LoggerProvider已配置。证据：
```
src/telemetry/setup.go:42
```
—— 添加了带批量处理器的OTLP日志导出器。
```
[~]
```
向后兼容桥接器。理由：无下游系统依赖span包中的span events。
```
[ ]
```
异常迁移。缺少证据；需重新检查。