2. OpenTelemetry 基础：Trace、Span、Context 的核心概念
在排查数据库迁移异步任务的故障时，仅靠日志和指标往往难以还原跨服务、跨线程的完整调用链路。OpenTelemetry 通过 Trace（追踪）、Span（跨度） 和 Context（上下文） 三个核心概念，为分布式系统提供了标准化的可观测性数据模型。理解这三者的关系，是构建有效追踪体系的第一步。
2.1 核心概念定义与关系
| 概念 | 定义 | 类比（一次数据库迁移） |
|---|---|---|
| Trace | 一个端到端的请求或工作流在分布式系统中的完整路径。由多个 Span 组成的有向无环图（DAG）。 | 一次完整的“数据库迁移任务”，从触发迁移脚本到最终完成数据校验的全过程。 |
| Span | Trace 中的单个工作单元，记录一个操作（如 RPC 调用、数据库查询、异步消息处理）的开始、结束、状态和元数据。 | 迁移任务中的“读取源表”、“写入目标表”、“执行数据校验”等每个独立步骤。 |
| Context | 携带 Trace 和 Span 标识信息的对象，用于在进程内或进程间传播追踪状态，确保 Span 能正确关联到同一个 Trace。 | 贯穿整个迁移任务的“任务 ID + 步骤 ID”，让不同模块知道当前属于哪个迁移批次。 |
关键理解： Trace 是 Span 的集合，Context 是 Span 之间的“胶水”。没有 Context，Span 就是孤立的日志片段；没有 Span，Trace 就是一个空壳。
2.2 Trace 与 Span 的层次结构
一个 Trace 通常由一个 根 Span（Root Span） 和多个 子 Span（Child Span） 组成。根 Span 代表整个请求的入口，子 Span 代表内部调用的子操作。Span 之间通过 父子关系（Parent-Child） 或 跟随关系（Follows-From） 连接。
2.3 Span 的核心属性
每个 Span 都包含一组标准属性，用于描述操作的特征和结果。在数据库迁移场景中，这些属性是定位故障的关键线索。
| 属性 | 说明 | 迁移场景示例值 |
|---|---|---|
| Span ID | 当前 Span 的唯一标识符（16 字节，通常以十六进制表示）。 | span-001 |
| Trace ID | 所属 Trace 的唯一标识符（16 字节）。 | trace-abc-123 |
| Parent Span ID | 父 Span 的 ID，用于构建父子关系。根 Span 无此属性。 | span-000 |
| Name | Span 的名称，描述操作内容。 | batch_write_to_target |
| Start Timestamp | 操作开始的时间戳（纳秒精度）。 | 2025-03-21T10:00:00.123456789Z |
| End Timestamp | 操作结束的时间戳（纳秒精度）。 | 2025-03-21T10:00:05.987654321Z |
| Status | 操作结果状态：Unset、Ok、Error。 |
Error（写入超时） |
| Attributes | 键值对形式的元数据，用于附加业务或技术信息。 | db.system=mysql, db.operation=insert, batch.size=5000 |
| Events | Span 生命周期内发生的带时间戳的日志事件。 | {"time": ..., "name": "exception", "attributes": {"exception.message": "Connection timeout"}} |
故障排查要点： 当迁移任务失败时，首先检查 Status 为
Error 的 Span，然后查看其 Events 中的异常信息，最后结合 Attributes 中的数据库类型、操作语句、批次大小等参数定位根因。
2.4 Context 的传播机制
Context 是 OpenTelemetry 实现分布式追踪的核心机制。它确保在一个服务中创建的 Span 信息，能够通过 Context Propagation（上下文传播） 传递给下游服务或异步任务，从而将分散的 Span 关联到同一个 Trace。
Context 传播分为两种方式：
- 进程内传播（In-Process Propagation）： 通过线程局部变量（ThreadLocal）或协程上下文（如 Go 的
context.Context）传递。适用于同步调用或同一线程内的异步回调。 - 进程间传播（Inter-Process Propagation）： 通过序列化 Context 信息到网络协议头（如 HTTP Headers、gRPC Metadata、消息队列属性）传递。适用于服务间 RPC 调用或跨进程的异步消息。
2.5 异步任务中的 Context 传递挑战
数据库迁移任务大量依赖异步操作（如批量写入、数据校验回调），Context 传递面临以下常见问题：
- 线程池切换： 任务提交到线程池后，新线程无法自动继承原线程的 Context，需要手动传递。
- 消息队列消费： 消费者从队列拉取消息时，必须从消息头中反序列化 Context，否则 Span 成为孤儿 Span。
- 回调/协程： 异步回调或协程（如 Kotlin Coroutines）中，Context 作用域可能丢失，需使用 OpenTelemetry 提供的 API 显式封装。
常见陷阱： 在异步迁移任务中，如果忘记在消息队列中传递 Trace Context，故障排查时将看到多个独立的 Trace，无法串联完整的迁移链路。务必在发送消息前调用
SpanContext.inject()，在消费消息后调用 SpanContext.extract()。
2.6 小结
Trace、Span 和 Context 构成了 OpenTelemetry 追踪的基石：
- Trace 是端到端的全景图，由 Span 组成。
- Span 是单个操作的可观测单元，包含时间、状态和元数据。
- Context 是 Span 之间的纽带，确保跨进程、跨异步边界的链路完整性。