2. Tempo Trace 基础：核心概念与数据模型
在开始慢 Trace 样本复盘之前，必须建立对 Tempo 数据模型的统一认知。本章将拆解 Trace 与 Span 的层级关系、标识体系、树形结构以及 Tempo 的存储模型，为后续的样本筛选与根因定位打下基础。
2.1 Trace 与 Span 概念
| 概念 | 定义 | 类比（图书） |
|---|---|---|
| Trace | 一次完整请求或事务的端到端调用链路，包含所有参与的服务、组件和操作。 | 一本书 |
| Span | Trace 中的最小工作单元，记录一个单一操作（如一次 RPC 调用、数据库查询、函数执行）的开始、结束、状态和元数据。 | 书中的一个章节 |
关键原则：一个 Trace 由多个 Span 组成，Span 之间通过父子关系形成完整的调用拓扑。Tempo 的存储和查询均以 Span 为最小粒度。
2.2 Trace ID 与 Span ID
每个 Trace 和 Span 都有全局唯一的标识符，用于关联和检索。
- Trace ID：一次请求的全局唯一标识，贯穿整个调用链。所有属于同一请求的 Span 共享同一个 Trace ID。
- Span ID：每个 Span 的唯一标识，用于区分 Trace 内的不同操作。
- Parent Span ID：父 Span 的 ID，用于构建 Span 之间的父子层级关系。根 Span（Root Span）的 Parent Span ID 为空。
复盘口径要点：在 Tempo 中查询慢 Trace 时，必须同时关注 Trace ID 和 Span ID。Trace ID 用于定位整条链路，Span ID 用于定位具体慢操作。Parent Span ID 用于还原调用链的上下游依赖。
2.3 Trace 树形结构
Trace 的树形结构是理解调用链拓扑的核心。根 Span 位于树顶，代表请求的入口；子 Span 代表下游调用或内部子操作。树的深度和广度反映了系统的调用复杂度。
2.4 Tempo 数据模型
Tempo 采用 Trace-by-Span 的存储模型，以 Span 为基本存储单元，通过 Trace ID 将同一 Trace 的所有 Span 聚合在一起。其核心数据结构如下：
| 字段 | 类型 | 说明 | 复盘用途 |
|---|---|---|---|
trace_id |
byte[] | Trace 全局唯一标识 | 关联整条调用链 |
span_id |
byte[] | Span 唯一标识 | 定位具体慢操作 |
parent_span_id |
byte[] | 父 Span ID，根 Span 为空 | 还原调用层级 |
start_time_unix_nano |
int64 | Span 开始时间（纳秒） | 计算耗时、排序 |
end_time_unix_nano |
int64 | Span 结束时间（纳秒） | 计算耗时 |
status |
Status | Span 状态（OK/ERROR） | 识别错误 Span |
attributes |
map | 键值对元数据（服务名、URL、DB 语句等） | 过滤、分组、定位 |
resource |
Resource | 资源信息（主机、容器、进程等） | 环境归属 |
复盘注意：Tempo 不存储完整的调用链拓扑，而是通过 Trace ID 和 Parent Span ID 在查询时动态构建树形结构。因此，
parent_span_id 的完整性直接影响 Trace 树的可视化质量。如果某些 Span 的 parent_span_id 缺失或错误，会导致调用链断裂或拓扑混乱。
2.5 Tempo 存储与查询架构
Tempo 的架构围绕高效存储和快速检索 Trace 数据设计，核心组件包括：
- Distributor：接收 Span 数据，进行校验和负载均衡，将数据分发到 Ingester。
- Ingester：将 Span 数据暂存到内存中，并定期刷新到后端存储（如 S3、GCS、本地磁盘）。
- Querier：接收查询请求，从 Ingester 和后端存储中检索 Span 数据，按 Trace ID 聚合后返回。
- Compactor：对后端存储中的数据进行合并、去重和索引优化，提升查询性能。
2.6 复盘口径中的关键数据模型字段
在慢 Trace 样本复盘时，以下字段是必须关注的核心维度：
复盘字段清单：
trace_id— 用于关联整条调用链，是样本的唯一标识。span_id+parent_span_id— 用于还原调用拓扑，定位慢 Span 的上下游。start_time_unix_nano+end_time_unix_nano— 用于计算 Span 耗时，识别慢操作。attributes["service.name"]— 用于区分不同服务，定位慢 Span 所属服务。attributes["http.url"]或attributes["db.statement"]— 用于定位具体的慢接口或慢 SQL。status.code— 用于识别错误 Span，区分慢 Trace 是否伴随错误。
2.7 本章小结
Trace 与 Span 是分布式追踪的基石，Trace ID 与 Span ID 是关联和定位的关键。Tempo 以 Span 为存储单元，通过 Trace ID 聚合，利用 Parent Span ID 构建树形结构。理解 Tempo 的数据模型和架构，是后续进行慢 Trace 样本筛选、耗时分析、根因定位的前提。