2. Trace数据模型：TraceID、Span、SpanKind、SpanStatus、Attributes、Events、Links的概念与数据结构，以及如何在Tempo中存储

分布式追踪的核心是构建一个端到端的请求调用链。理解其数据模型是进行高效查询与存储优化的前提。本章将深入剖析Trace数据模型的各个核心组件，并揭示Grafana Tempo如何将这些结构化数据转化为可检索的存储单元。

2.1 核心概念与数据结构

一个完整的Trace由一组具有因果关系的Span组成，它们通过TraceID关联，共同描述一个请求在分布式系统中的完整生命周期。

2.2 Span的生命周期与关系

Span通过ParentSpanID构建出树形层级结构。一个没有ParentSpanID的Span称为根Span（Root Span），代表整个Trace的入口点。

2.3 SpanKind与SpanStatus的语义

SpanKind 定义了Span的通信方向，对Tempo的查询和延迟分析至关重要：

• CLIENT：表示该Span封装了一个对下游服务的调用请求。
• SERVER：表示该Span封装了一个来自上游服务的请求处理。
• PRODUCER / CONSUMER：用于消息队列场景，分别代表消息的发送和接收。
• INTERNAL：表示该Span代表一个内部操作，不涉及外部网络调用。

SpanStatus 是判断服务健康度的关键指标。在Tempo中，你可以通过{ .status = ERROR }快速过滤出所有失败的Span：

# 查询所有状态码为ERROR的Span
{ .status.code = "ERROR" }

# 查询特定错误描述的Span
{ .status.code = "ERROR" && .status.description = "timeout" }

2.4 Attributes、Events与Links的深度应用

这三个组件为Span提供了丰富的上下文信息，是Tempo实现高基数标签查询的基础。

• Attributes：推荐将HTTP方法、URL、数据库语句、服务版本等关键业务/技术元数据作为Attributes。Tempo会为这些键值对建立索引，实现毫秒级过滤。
• Events：用于记录异常堆栈、日志快照或自定义里程碑。例如，在发生异常时，可以记录一个名为exception的Event，并附带exception.message和exception.stacktrace属性。
• Links：在异步处理或消息队列场景中，一个Span可能需要关联到另一个Trace中的Span。例如，一个消息生产者Span可以Link到消费者Span，即使它们属于不同的Trace。

2.5 Tempo中的存储模型

Grafana Tempo采用对象存储（如S3、GCS、Azure Blob）作为后端，其存储模型围绕“Trace”和“Block”两个核心概念设计。

Tempo的存储流程可以概括为以下步骤：

1. 接收与批处理： Tempo接收来自OpenTelemetry Collector或Jaeger Agent的Span数据，并将其按TraceID分组。
2. 构建Block： 当满足一定条件（如时间窗口、数据量大小）时，Tempo将一组完整的Trace封装成一个Block。Block是Tempo中不可变的最小存储单元。
3. 写入对象存储： Block被序列化并写入后端对象存储。每个Block包含多个文件：
   • data：存储所有Span的原始数据（通常使用Protocol Buffers编码）。
   • index：一个从TraceID到data文件中偏移量的映射，用于快速定位Trace。
   • bloom filter：一个概率性数据结构，用于快速判断一个TraceID是否存在于该Block中，避免不必要的磁盘I/O。
   • meta.json：包含Block的元数据，如时间范围、Span数量、包含的Attributes键值对等。

2.6 查询路径与索引优化

理解Tempo的存储模型后，其查询路径就变得清晰：

• TraceID查询： 直接通过TraceID查找。Tempo会遍历所有Block的Bloom Filter，快速排除不包含该TraceID的Block，然后通过Index在Data文件中定位并反序列化。
• 标签查询： 通过Attributes进行过滤。Tempo会利用Block的meta.json中的标签信息，只扫描包含相关标签的Block，大幅减少扫描范围。

索引优化的核心在于合理配置搜索标签（Search Tags）。你可以通过Tempo的配置文件指定哪些Attributes需要被索引：

# tempo.yaml 配置片段
overrides:
  defaults:
    search:
      tags:
        - "http.method"
        - "http.status_code"
        - "service.name"
        - "db.system"

只有被列入search.tags列表的Attributes才会被写入Block的元数据中，用于加速标签查询。未被索引的标签仍然可以查询，但Tempo需要扫描所有Block的Data文件，性能会显著下降。