4. 数据模型与索引：Trace ID索引、服务名称索引、标签索引的存储结构与查询原理

在Tempo链路存储引擎中，数据模型的设计直接决定了查询性能的上限。值班台查询场景（如按Trace ID精确查找、按服务名称聚合、按标签过滤）对索引结构提出了截然不同的要求。本章深入剖析三种核心索引的底层存储结构与查询路径，帮助运维人员理解“为什么慢”以及“如何优化”。

4.1 数据模型总览：从Span到索引行

Tempo的存储层基于对象存储（如S3、GCS）或本地文件系统，采用“Trace → Block → Index”的三层架构。每个Span被写入后，首先按Trace ID聚合为完整的Trace记录，再打包为不可变的Block文件。索引则独立于数据块构建，用于加速查询。

4.2 Trace ID索引：精确查找的基石

Trace ID索引是Tempo中性能最高的索引类型，专为“给定Trace ID，查找完整Trace”场景设计。其存储结构采用哈希表 + 稀疏偏移量的组合方式。

4.2.1 存储结构

• 哈希表：将Trace ID（128位或64位）哈希后映射到固定大小的桶（Bucket）中，每个桶存储指向Block内偏移量的指针。
• 稀疏偏移量：Block内的Span数据按写入顺序排列，索引仅记录每个Trace在Block中的起始偏移量和长度，避免存储完整Span。
• 内存映射：索引文件在查询节点启动时通过mmap加载到内存，实现O(1)查找。

4.2.2 查询原理

1. 接收Trace ID查询请求。
2. 对Trace ID进行哈希计算，定位到对应的哈希桶。
3. 在桶内遍历（通常仅1-2个条目）找到匹配的Block ID和偏移量。
4. 根据偏移量直接从Block中读取Span数据。
5. 反序列化并组装为完整Trace返回。

// 伪代码：Trace ID 索引查询
func lookupTraceID(traceID string) *Trace {
    hash := hashTraceID(traceID)
    bucket := traceIndex.buckets[hash % numBuckets]
    for _, entry := range bucket {
        if entry.traceID == traceID {
            block := openBlock(entry.blockID)
            data := block.readAt(entry.offset, entry.length)
            return deserializeTrace(data)
        }
    }
    return nil // 未找到
}

4.3 服务名称索引：聚合查询的加速器

服务名称索引用于支持“查询某个服务在指定时间窗口内的所有Trace”这类聚合场景。其存储结构为倒排列表（Inverted List），以服务名称为键，存储该服务下所有Trace ID的列表。

4.3.1 存储结构

4.3.2 查询原理

1. 解析查询条件：服务名称 + 时间范围。
2. 在词典中二分查找服务名称，获取倒排列表指针。
3. 利用跳表快速定位到时间范围内的起始位置。
4. 顺序读取倒排列表中的Trace ID，直到超出时间范围。
5. 对每个Trace ID回查Trace ID索引，获取完整Trace数据。

4.4 标签索引：灵活过滤的代价

标签索引支持按任意标签键值对进行过滤，例如查询所有 http.status_code=500 的Trace。其存储结构也是倒排列表，但键为标签键值对组合（如 http.status_code=500），值为Trace ID列表。

4.4.1 存储结构

• 复合键：标签键和标签值拼接为字符串作为索引键，例如 http.method:GET。
• 多级词典：先按标签键分组，再按标签值分组，减少词典大小。
• 位图索引（可选）：对于基数较低的标签（如 error=true），Tempo支持使用Roaring Bitmap替代倒排列表，大幅降低存储空间和查询时间。

4.4.2 查询原理

1. 解析标签查询条件：key=value。
2. 在标签词典中查找对应的倒排列表或位图。
3. 如果查询包含多个标签（AND条件），对多个倒排列表执行交集运算。
4. 获取最终的Trace ID列表。
5. 回查Trace ID索引获取完整数据。

// 伪代码：多标签 AND 查询
func lookupTags(tags map[string]string) []TraceID {
    var result []TraceID
    first := true
    for key, value := range tags {
        postingList := tagIndex.lookup(key + ":" + value)
        if first {
            result = postingList
            first = false
        } else {
            result = intersect(result, postingList) // 交集运算
        }
    }
    return result
}

4.5 索引优化实战建议