Grafana Tempo 3.0 升级全指南:架构重构、破坏性变更与配置迁移实战
Grafana Tempo 3.0 升级全指南:架构重构、破坏性变更与配置迁移实战
本文以仓库根目录下的 CHANGELOG.md 为主线,系统梳理 Grafana Tempo 自 2.x 到 3.0 的关键演进:ingester 模块的移除与 live-store、block-builder 新架构的落地、近实时查询一致性保证、TraceQL 指标查询能力的持续增强,以及升级前必须处理的破坏性配置变更。读完本文,你将掌握 3.0 的架构全景、受影响配置项的完整清单,以及借助 tempo-cli migrate 系列命令完成平滑迁移的实操方法。
一、3.0 时代:从 ingester 到 live-store 与 block-builder 的架构重构
1.1 ingester 模块的彻底移除
Tempo 3.0 是一次以"去 ingester 化"为核心的架构换代。CHANGELOG 中明确记录了一系列 BREAKING CHANGE:
- 移除 ingester 模块(#6959、#6504),随之删除了 ingester 与 compactor 相关告警(#6369);
- 移除遗留的 ingester 配置(#6667)与
ingest.enabled配置项(#6873); - 移除
v2块编码与 compactor 组件(#6273),并连带删除了仅服务于 v2 的 CLI 命令:list block、list index、view index、gen index、gen bloom; - 移除
querier.query_live_store配置(#7048),升级时该字段必须从配置中删除; - 弃用
query_frontend.rf1_after(#6969),非指标查询路径现在无论副本因子如何都会查询所有块,以简化 2.x → 3.0 的迁移。
1.2 新组件:live-store 与 block-builder
取代 ingester 的是两个新模块,对应仓库目录 modules/livestore 与 modules/blockbuilder:
- live-store:负责从 Kafka 消费实时追踪数据、维护本地 WAL 块,并对外提供近实时查询。3.0 中它还接管了原 metrics-generator localblocks 处理器的职责(#6555 移除了 localblocks processor 及其本地块存储管线,#6506、#6535 将 livestore 与 metrics-generator 解耦),并下线了 livestore 的 MetricsGenerator 查询服务(#6615);
- block-builder:负责把 Kafka 中的分区数据批量构建为后端存储块。单机模式(single-binary)下,distributor 的本地摄取数据可绕过 Kafka 直接推送至 live-store 与 metrics-generator(#6729)。
all target 已被调整为 3.0 兼容模式,并移除了 scalable-single-binary target(#6283)。
二、配置中心化:block 与 WAL 配置的收敛
2.1 统一到 storage.trace.block
3.0 将 block 与 WAL 的配置进行了集中化管理(#6647):block_builder 和 live_store 现在始终使用 storage.trace.block 的全局设置,各模块自身的 block 配置字段被移除。这也修正了此前 block-builder 与 live-store 未遵循全局存储块版本配置的问题(#6451、#6509)。
从源码看,modules/livestore/config.go 中 BlockConfig common.BlockConfig 字段标注为"not configurable via YAML"(不可通过 YAML 配置),与 modules/blockbuilder/config.go 中的注释一致,即块级设置由存储段注入。同时 dedicated columns 的 fallback 逻辑也已修复(#6647):当 overrides 未设置 parquet_dedicated_columns 时,回退到 storage.trace.block.parquet_dedicated_columns。
2.2 默认值对齐与 WAL 瘦身
为降低默认资源占用并统一查询语义,#6974 调整了 livestore 相关默认值:
| 配置项 | 旧默认值 | 新默认值 | 说明 |
|---|---|---|---|
max_block_duration |
1m | 30s | 块切割周期 |
max_block_bytes |
100MiB | 50MiB | 块大小上限 |
complete_block_timeout |
1h | 20m | 块完成超时 |
metrics query_backend_after |
30m | 15m | 指标查询回退到后端的时间点 |
modules/livestore/config.go 中可以看到这些默认值的落地:CompleteBlockTimeout = 20 * time.Minute、MaxBlockDuration = 30 * time.Second、MaxBlockBytes = 50 * 1024 * 1024,并提供了 -livestore.complete-block-timeout、-livestore.concurrent-blocks 等 CLI 标志。
2.3 compactor CLI 标志去重
#6909 移除了 CompactorConfig CLI 标志中重复的 compaction 前缀,受影响的标志为:
compaction.block-retentioncompaction.max-objects-per-blockcompaction.max-block-bytescompaction.compaction-window
三、近实时查询的一致性保证
3.1 默认开启的 query_end_cutoff
3.0 的一项关键语义变化是:近实时数据查询现在通过"失败"来保证结果的完整性(#7210)。query_frontend.query_end_cutoff 默认值为 30s,live_store.fail_on_high_lag 默认值为 true。
在 modules/frontend/config.go 与 modules/frontend/metrics_query_range_handler.go 中可以看到实现:查询结束时间会被钳制到 now - query_end_cutoff;若查询窗口完全落在 cutoff 内,会返回 errQueryWindowWithinEndCutoff 错误("query window falls entirely within query_end_cutoff")。其默认值 30s 定义于 modules/frontend/config.go。
同时,近实时读取配置也被收敛(#6507):query_frontend.search.query_ingesters_until 被移除,只保留 query_frontend.search.query_backend_after。
3.2 live-store 就绪与滞后控制
围绕"何时可以安全查询最近数据",3.0 引入了完整的就绪与滞后机制:
readiness_target_lag与readiness_max_wait(#6238、#6405):设置后,live-store 在 Kafka 滞后降到目标值之前不会报告/ready;fail_on_high_lag(#6363、#6567、#7066):滞后过高且无法保证结果完整时,SearchRecent 与 QueryRange 查询会直接失败,而不是返回不完整结果(#6911 修复了查询前先检查就绪状态的问题)。
modules/livestore/config.go 中 ReadinessTargetLag 默认为 0(关闭等待,向后兼容),ReadinessMaxWait 默认 30m,而 FailOnHighLag 默认 true。
3.3 崩溃安全的两阶段块回收
#7132 中默认值为 2m。
四、TraceQL 与指标查询能力的增强
4.1 AST 优化与语义收紧
- 数组等价改写(#6353,BREAKING):相同属性上的多个条件会被重写为数组等价形式,但
!=与!~的数组匹配语义略有变化,且正则字面量规则更严格; - 可跳过的 AST 变换(#7012);
- 指标查询比较运算符(#6474):TraceQL Metrics 查询支持比较运算符;
- 默认最大时长上调(#6285 中
MaxDuration: 24 * time.Hour; - step 间隔对齐新时间戳列(#6413):默认 step 间隔与 vParquet5 的低分辨率时间戳列对齐。
4.2 更快的数据读取路径
指标查询新增了实验性快速读取路径(#6359、#6849):多数指标查询可通过 query hint spanonly_fetch=true(需开启 unsafe_query_hints)或 per-tenant override 选择该路径。
4.3 span 采样补偿(span multiplier)
为补偿基于头部采样(head-based sampling)造成的数据稀释:
- 新增
span_multiplier_keyoverride(#6260),租户可指定用于 span multiplier 取值的属性键; - 支持从 W3C tracestate 的 OTel 概率采样阈值提取 multiplier(#6684),通过
enable_tracestate_span_multiplier开启。
4.4 查询结果正确性修复
3.0 修复了多个影响结果正确性的缺陷,值得关注:除零报错与 intPow 挂起(#6580、#6581)、blob 列上的错误搜索结果(#6815)、vParquet5 中事件属性写入专属列时的 buffer-reuse 污染问题(#6914)。
五、overrides:新的作用域与优先级语义
3.0 对 overrides 模块做了多处结构性调整,这是升级中最容易踩坑的部分。
5.1 默认禁用 legacy 扁平 overrides
#6741 默认禁用旧的扁平(无作用域)overrides:检测到 legacy overrides 时 Tempo 将拒绝启动。可临时通过 enable_legacy_overrides: true 或 -config.enable-legacy-overrides=true 恢复,legacy 格式将在未来版本移除。
源码证据位于 modules/overrides/config.go(EnableLegacyOverrides bool)与 modules/overrides/overrides.go(启动时校验并提示迁移)。对应的测试用例在 modules/overrides/overrides_test.go,覆盖了"拒绝 legacy"与"接受 legacy"两种分支。
5.2 metrics_generator.processors 优先级反转
#7176 是一个容易混淆的破坏性变更:user-configurable overrides 中的 metrics_generator.processors 不再与 runtime overrides 合并,而是像其他所有 user-configurable 配置一样完全覆盖 runtime overrides。设置 processors: [] 即为该租户禁用全部 processor。
5.3 新增 per-tenant override 能力
- per-label 基数限制(#6414):
max_cardinality_per_label,并新增估算 per-label 基数需求的指标; - trace ID 左填充(#6489):支持按租户对 trace ID 做左填充;
- overrides 扩展机制(#6758):引入 per-tenant overrides 的扩展点。
5.4 过滤策略与校验
#6407 对 user-configurable overrides API 中的 filter policies 做了深度校验;#6411 允许通过 API 设置 span_name_sanitization;#6435 修复了运行时热加载该配置的问题。
六、摄取路径:RetryInfo、重复维度与丢弃追踪
6.1 RetryInfo 默认开启
#7088 与 modules/distributor/config.go 中定义。
6.2 重复维度与属性截断
- 允许 span metrics 与服务图使用重复维度(#6288):不同埋点库可能产生
deployment.environment与deployment_environment这类语义相同但写法不同的维度; - 截断可观测性增强(#6400、#6467):记录被截断的超大属性;
- 无效 trace/span ID 丢弃追踪(#6799)。
七、运维与可观测性
7.1 单机模式与部署
- 单机示例改用本地后端(#7033);
- jsonnet 新增 KEDA 水平 Pod 自动扩缩容支持(#6970),适用于微服务部署;
- block-builder StatefulSet 增加 emptyDir 数据卷(#6648);
- livestore 同 zone Pod 反亲和(#6757);
- Docker 示例暴露 OTLP HTTP 与 gRPC 端口(#6296)。
7.2 性能与内存
- live-store 无锁读 + 两阶段回收(#7132);
- span 去重(#6539):block-builder 在块创建时对 trace 内重复 span 去重,并以
tempo_block_builder_spans_deduped_total指标追踪; - WAL 写入路径减少分配(#6863);移除 vParquet5 压缩/建块/CLI 中的显式
runtime.GC()(#6603); - native histogram 双格式发射(#6910):所有 promauto 注册的直方图(含
tempo_request_duration_seconds)同时发射 classic 与 native 两种格式,现有采集器不受影响。
7.3 新增指标速查
| 指标 | 说明 | 出处 PR |
|---|---|---|
tempo_block_builder_spans_deduped_total |
block-builder 去重 span 数 | #6539 |
tempo_distributor_metrics_generator_tenant_ring_size |
generator ring 大小 | #5686 |
| livestore 块切割原因指标 | 追踪块切割原因 | #6922 |
| 查询作业分布直方图 | 追踪每次查询的作业分布 | #6343 |
7.4 安全与依赖
- S3 SSE-C
encryption_key作为机密处理,修复 CVE-2026-28377(#6711); - 升级至 Go 1.26.3(#7423);
- 停止发布 32 位 ARM 二进制归档(#7106),继续提供 amd64 与 arm64。
八、升级指南:破坏性变更检查清单与迁移工具
8.1 升级前必须处理的配置项
| 需处理项 | 处理方式 | 来源 PR |
|---|---|---|
querier.query_live_store |
删除 | #7048 |
ingest.enabled |
删除 | #6873 |
query_frontend.search.query_ingesters_until |
改用 query_backend_after |
#6507 |
compaction.* CLI 标志 |
去掉 compaction 前缀 |
#6909 |
| legacy 扁平 overrides | 迁移到 scoped 格式或临时开启 enable_legacy_overrides |
#6741 |
mem-ballast-size-mbs CLI 标志 |
删除 | #6403 |
query_frontend.rf1_after |
弃用,无需配置 | #6969 |
| v2 专属 CLI 命令 | 删除(list block、gen index 等) | #6273 |
8.2 使用 tempo-cli migrate 系列命令
3.0 强化了迁移工具链,对应源码位于 cmd/tempo-cli:
tempo-cli migrate config(#6982):将 Tempo 2.x 配置迁移到 3.0 格式;tempo-cli migrate overrides-config重写(#6793):帮助把 legacy 扁平 overrides 迁移到新的 scoped 格式;tempo-cli migrate overrides-per-tenant(#6793):新增的 per-tenant overrides 迁移命令。
8.3 tempo-cli 时间参数标准化
#6458 是一项会影响脚本的破坏性变更:tempo-cli 所有命令的 start/end 参数统一支持相对时间(now、now-1h)并统一使用 RFC3339。例如 query search 命令不再接受无时区的 2024-01-01T00:00:00,应使用 2024-01-01T00:00:00Z 或相对时间。
8.4 建议的升级顺序
结合 CHANGELOG 与 3.0 架构变化,推荐顺序:
- 在测试环境用
tempo-cli migrate config与tempo-cli migrate overrides-config校验并迁移配置; - 确认 legacy overrides 已全部转为 scoped 格式(否则 Tempo 会拒绝启动);
- 删除所有已移除的配置字段(见 8.1 清单);
- 验证
query_end_cutoff(默认 30s)对现有查询窗口的影响,必要时显式调整; - 评估
metrics_generator.processors覆盖语义变化对多租户的影响; - 由于
alltarget 已切换为 3.0 兼容模式且scalable-single-binary已移除,部署清单需按新 target 调整(参考 example/docker-compose 与 operations/jsonnet 中的示例)。
九、2.10.x 维护分支亮点
3.0 正式版之前,2.10.x 系列也沉淀了大量值得关注的能力与修复:
- vParquet5 正式发布(#6219):支持整数与事件的专属属性列,显著改善高基数/高长度属性下的性能与 TraceQL 查询速度,并新增
childCountintrinsic; - TraceQL 语言扩展:
minInt/maxInt(#5982)、attribute = nil(#4905); - MCP Server 支持(#5212;
- 安全更新:apache/thrift v0.23.0(#7120)、golang.org/x/crypto v0.52.0(#7262)、golang.org/x/net v0.55.0(#7129)等;
- search 默认
max_result_limit提高至 256*1024(#6525 中MaxLimit: 256 * 1024一致。
十、版本演进脉络:从 v0.3 到 v3.0 的关键节点
通过 CHANGELOG 可以清晰看到 Tempo 存储与查询引擎的演进主线:
- v0.3(2020-11):bloom filter 分片(破坏性变更,旧数据不可查询);
- v1.0(2021-06):多租户开关更名为
-multitenancy.enabled; - v1.4(2022-04):引入 metrics-generator 可选组件(#1282);
- v1.5(2022-08):引入 parquet 块格式(#1479);
- v2.0(2023-01):TraceQL 支持、Parquet 后端 GA 并成为默认编码、通用 forwarder;
- v2.3(2023-10):vParquet3 专属属性列、overrides 重构为 scoped 格式;
- v2.4(2023-12):TraceQL 指标查询(#3227 等)、多租户查询、缓存重构;
- v2.5(2024-02):vParquet4(links、events、arrays)、gRPC 流式端点;
- v2.6(2024-04):vParquet4 成为默认编码、
/api/metrics/query即时查询端点; - v2.7–v2.9(2024):TraceQL 指标函数持续扩充(sum/min/max/avg/quantile/histogram over_time)、compare()、结构化运算符、实验性 Tempo Rearchitecture(backend-scheduler、live-store);
- v2.10(2025):vParquet5 正式版;
- v3.0(2025):移除 ingester 与 v2 编码,live-store/block-builder 架构落地,近实时一致性保证默认开启。
这条主线印证了 CHANGELOG 是理解 Tempo 架构演进的第一手资料——从 v2 编码 + ingester 的经典架构,逐步走向"Parquet 全链路 + Kafka 摄取 + 无 ingester"的 3.0 新架构。
结语
Tempo 3.0 的核心价值在于:通过移除 ingester、统一 block/WAL 配置、默认保证近实时查询一致性与集中化 overrides 语义,将 2.x 积累的实验性架构(live-store、block-builder)固化为正式能力。升级时请务必对照 CHANGELOG.md 中的 BREAKING CHANGE 逐项核对配置,并善用 tempo-cli migrate config、tempo-cli migrate overrides-config 与 tempo-cli migrate overrides-per-tenant 三个迁移命令,将手工排查的工作量降到最低。