Grafana Tempo 3.0 升级全指南:架构重构、破坏性变更与配置迁移实战

原创2026-09-17 19:10:441,864 阅读
文章标签:后端链路追踪可观测性对象存储微服务

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-retention
  • compaction.max-objects-per-block
  • compaction.max-block-bytes
  • compaction.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_key override(#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 架构变化,推荐顺序:

  1. 在测试环境用 tempo-cli migrate config 与 tempo-cli migrate overrides-config 校验并迁移配置;
  2. 确认 legacy overrides 已全部转为 scoped 格式(否则 Tempo 会拒绝启动);
  3. 删除所有已移除的配置字段(见 8.1 清单);
  4. 验证 query_end_cutoff(默认 30s)对现有查询窗口的影响,必要时显式调整;
  5. 评估 metrics_generator.processors 覆盖语义变化对多租户的影响;
  6. 由于 all target 已切换为 3.0 兼容模式且 scalable-single-binary 已移除,部署清单需按新 target 调整(参考 example/docker-compose 与 operations/jsonnet 中的示例)。

九、2.10.x 维护分支亮点

3.0 正式版之前,2.10.x 系列也沉淀了大量值得关注的能力与修复:

  • vParquet5 正式发布(#6219):支持整数与事件的专属属性列,显著改善高基数/高长度属性下的性能与 TraceQL 查询速度,并新增 childCount intrinsic;
  • 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 三个迁移命令,将手工排查的工作量降到最低。

登录后查看全文
tempo