4. Trace数据模型：Span结构、TraceID与SpanID、Attributes与Events、Resource与Scope

分布式追踪的数据模型是理解Tempo检索机制的基础。Tempo原生兼容OpenTelemetry（OTel）数据模型，所有检索加速策略——从TraceID路由到Span级过滤——都建立在对Span、TraceID、SpanID、Attributes、Events、Resource、Scope等核心概念的精确理解之上。本章将逐一拆解这些概念，并揭示它们如何影响Tempo的存储与查询路径。

4.1 Span结构：追踪的最小原子单元

Span（跨度）是分布式追踪中描述一次操作的最小工作单元。一个完整的Trace由多个Span通过父子关系或因果关系连接而成。每个Span记录了一个操作在特定服务中的开始时间、结束时间、状态以及上下文信息。

一个标准的Span结构包含以下关键字段：

4.2 TraceID与SpanID：追踪的坐标系统

TraceID和SpanID构成了分布式追踪的坐标系统。理解它们的生成规则和存储方式，是优化Tempo检索性能的关键。

4.2.1 TraceID：全局唯一标识

• 长度：OpenTelemetry标准支持16字节（128位）或32字节（256位）两种长度。Tempo默认使用16字节TraceID。
• 生成规则：通常由入口服务（如API网关）生成，包含时间戳、随机数或机器标识。Tempo不强制TraceID的生成算法，但推荐使用高熵随机数以避免哈希冲突。
• 存储影响：Tempo将TraceID作为分片键（Shard Key）进行数据分布。TraceID的哈希值决定了Span数据落在哪个Ingester或Storage Bucket中。
• 检索加速：按TraceID查询是Tempo最高效的检索路径，直接命中分片，无需全表扫描。

4.2.2 SpanID：局部唯一标识

• 长度：固定8字节（64位）。
• 生成规则：由产生Span的SDK自动生成，保证在同一个Trace内唯一即可。
• 父子关系：通过ParentSpanID字段关联。根Span的ParentSpanID为空。
• 检索场景：TraceQL支持span_id精确查询，适用于已知特定SpanID的深度排查场景。

4.3 Attributes与Events：Span的元数据与事件

4.3.1 Attributes：结构化的键值对元数据

Attributes是Span的元数据载体，以键值对（Key-Value Pair）形式存在。Tempo将Attributes作为TraceQL过滤的核心维度，直接影响检索效率。

Attributes的常见分类：

4.3.2 Events：Span生命周期内的结构化日志

Events是Span内部发生的、带时间戳的结构化事件记录。与Attributes不同，Events可以出现多次，且每个Event都包含独立的时间戳和属性集。

Events的典型应用场景：

• 异常堆栈捕获：当Span状态变为Error时，SDK自动注入exception事件，包含exception.type、exception.message、exception.stacktrace等属性。
• 消息队列偏移量：记录消息的offset、partition、consumer.group等信息。
• 缓存命中/未命中：记录缓存操作的cache.hit、cache.key等事件。
• 自定义业务里程碑：记录业务处理过程中的关键节点，如payment.authorized、inventory.reserved。

// Events在Span中的JSON表示示例
{
  "events": [
    {
      "timeUnixNano": "1712345678000000000",
      "name": "exception",
      "attributes": [
        {"key": "exception.type", "value": {"stringValue": "java.lang.NullPointerException"}},
        {"key": "exception.message", "value": {"stringValue": "Cannot invoke method on null object"}},
        {"key": "exception.stacktrace", "value": {"stringValue": "at com.example.service... (line 42)"}}
      ]
    },
    {
      "timeUnixNano": "1712345679000000000",
      "name": "cache.miss",
      "attributes": [
        {"key": "cache.key", "value": {"stringValue": "user:profile:12345"}},
        {"key": "cache.backend", "value": {"stringValue": "redis"}}
      ]
    }
  ]
}

4.4 Resource与Scope：Span的归属上下文

Resource和Scope提供了Span的归属上下文信息，是Tempo实现跨服务、跨库检索的关键维度。

4.4.1 Resource：产生Span的实体信息

Resource描述产生Span的物理或逻辑实体，通常在整个服务生命周期内保持不变。Tempo将Resource信息存储在独立的索引中，支持高效的resource.*过滤。

Resource的典型属性：

4.4.2 Scope：产生Span的库/框架信息

Scope描述产生Span的Instrumentation库（如OpenTelemetry SDK、Spring Boot Starter、gRPC拦截器）的信息。Scope在Tempo中用于区分不同框架产生的Span，支持scope.*过滤。

Scope的典型属性：

• scope.name：库名称，如io.opentelemetry.spring-webmvc-6.0
• scope.version：库版本，如1.32.0

4.5 数据模型对Tempo检索性能的影响

理解数据模型后，可以总结出以下影响Tempo检索性能的关键原则：

1. TraceID是最高效的检索键：按TraceID查询直接命中分片，延迟通常在10ms以内。
2. Resource属性是第二高效的过滤维度：Tempo为resource.service.name等常用属性建立了独立索引。
3. Span Attributes的过滤效率取决于基数：低基数属性（如http.status_code）过滤效率高；高基数属性（如user.id）需要配合时间范围使用。
4. Events查询需要遍历Span：Events不建立独立索引，查询效率低于Attributes。
5. Scope过滤适用于库级问题排查：在常规故障场景中，优先使用Resource和Attributes过滤。