Grafana Tempo 升级实战指南：从 2.x 迁移到 3.0 / 3.1 的破坏性变更与配置迁移-北京尧图网络

后端可观测性链路追踪【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址https://gitcode.com/GitHub_Trending/tempo1/tempo点击查看免费下载本文面向自托管self-managed部署的 Grafana Tempo 用户系统梳理从 Tempo 2.x 升级到 3.0、再到 3.1 过程中涉及的全部破坏性变更Redis / Memcached 缓存配置重构、Trace by ID 动态分片、ingester 与 compactor 架构移除、legacy overrides 默认禁用等。阅读本文后你将掌握每个版本升级前必须完成的配置迁移清单、准确的 YAML 前后对照示例以及如何借助tempo-cli migrate命令与statusAPI 自动化和验证迁移过程从而在非生产环境完成充分验证后再安全上线生产。任何 Tempo 版本升级都存在引入破坏性变更的可能。因此在将升级推广到生产环境之前务必先在非生产环境中充分测试。升级流程会因后续版本的具体改动而不同且本升级指南仅适用于自托管安装不适用于 Grafana Cloud。关于升级到 Tempo 2.x 的说明请参阅 2.10 版本的升级文档关于每个版本的详细变更可查阅本仓库的 Release notes 目录。一个实用提示升级前后你可以通过 Tempo 安装中的statusAPI 端点检查当前生效的配置选项快速确认配置是否被正确解析。升级到 Tempo 3.1Redis 缓存配置变更Tempo 3.1 将 Redis 缓存客户端升级到github.com/redis/go-redis/v9并重新设计了缓存配置对应 PR 7337。核心变化包括Redis Cluster 成为默认路由模式、移除 Redis Sentinel 支持、重命名若干 YAML 键、以 dskit 风格的 TLS 块替换原有 TLS 配置且配置无效时失败关闭fail closed。如果你不使用 Redis 缓存则无需任何操作。将单节点 Redis 显式接入单节点客户端路由现在变为显式声明。此前 Tempo 会根据端点数量推断路由方式这会导致解析到单个主机的集群配置端点例如 AWS ElastiCache 配置端点被静默选中为单节点模式。现在默认目标是 Redis Cluster需要设置single_node: true来显式接入单节点客户端。迁移前cache: caches: - redis: endpoint: redis:6379迁移后cache: caches: - redis: endpoint: redis:6379 single_node: true如果单节点配置未设置single_node: trueTempo 仍会启动但当服务器对CLUSTER SLOTS命令返回错误时集群客户端会在首次连接尝试时失败。此外Redis Cluster 部署现在要求 Redis 7因为 Tempo 通过COMMAND INFO通告的multi_shard请求策略来扇出跨槽位的MGET/DEL操作。这一变更的源码实现在 pkg/cache/redis_client.goRedisConfig结构体中的SingleNode bool \yaml:single_node字段采用了反转设计——Go 零值对应期望的默认值Cluster这样缺失的字段永远不会静默翻转路由方式。构造函数NewRedisClient中路由是显式的cfg.SingleNode为真时调用redis.NewClient否则调用redis.NewClusterClient彻底取代了旧版基于地址数量的UniversalClient推断逻辑对应代码注释中明确提到的 AWS ElastiCache 场景。集群路径下还通过cc.GetResolver().SetFallbackResolver(cc.NewDynamicResolver())接入动态解析器使MGET/DEL等跨槽位多键命令按multi_shard请求策略分片执行避免CROSSSLOT 错误——这正是文档要求 Redis 7 的原因。迁移 Redis SentinelRedis Sentinel 支持已被移除。以下 YAML 键及其对应的 CLI 标志不再存在master_name/-redis.master-namesentinel_username/-redis.sentinel-usernamesentinel_password/-redis.sentinel-password请迁移到单节点 Redis 或 Redis Cluster。重命名idle_timeout和max_connection_age两个连接池键更名为与 go-redis v9 API 一致旧键新键idle_timeoutconn_max_idle_timemax_connection_ageconn_max_lifetime迁移前cache: caches: - redis: idle_timeout: 5m max_connection_age: 1h迁移后cache: caches: - redis: conn_max_idle_time: 5m conn_max_lifetime: 1h在源码 pkg/cache/redis_client.go 中这两个字段分别对应ConnMaxIdleTime time.Duration连接空闲超过该时长即关闭值为零则不关闭与ConnMaxLifetime time.Duration连接存活超过该时长即关闭值为零则不按年龄关闭并透传给 go-redis v9 的redis.Options/redis.ClusterOptions。替换 TLS 块原来的最小tls_enabled/tls_insecure_skip_verify配置对被替换为 dskit 风格的 TLS 块。已有配置仍然有效新字段均为可选项。新字段用途tls_cert_path客户端证书文件路径tls_key_path客户端私钥文件路径tls_ca_pathCA 证书文件路径tls_server_name覆盖服务器证书上期望的名称tls_insecure_skip_verify跳过服务器证书校验语义不变tls_cipher_suites覆盖默认密码套件列表逗号分隔tls_min_version覆盖默认最小 TLS 版本如VersionTLS12无效的 TLS 配置现在失败关闭若tls_enabled: true但 TLS 配置无法组装Tempo 会在缓存构造阶段直接返回错误而不再静默降级为明文连接。这对应 pkg/cache/redis_client.go 中NewRedisClient的实现——cfg.TLS.GetTLSConfig()出错时立即return nil, fmt.Errorf(redis: invalid TLS configuration: %w, err)从源码层面保证了绝不静默回退明文的操作者意图。新的 Redis Cluster 路由选项以下选项是新增的、可选的仅在使用默认集群客户端single_node: false时生效在单节点路径上会被忽略cache: caches: - redis: route_by_latency: false # 将只读命令路由到最低延迟节点 route_randomly: false # 将只读命令路由到随机节点 read_only: false # 允许在副本节点上执行只读命令。读到的数据可能过期 max_redirects: 3 # 遇到 MOVED/ASK 响应时最多跟随的重定向次数 min_idle_conns: 0 # 连接池中保持的最小空闲连接数这些字段在源码中分别对应RedisConfig的RouteByLatency、RouteRandomly、ReadOnly、MaxRedirects、MinIdleConns。值得注意的是max_redirects的默认值go-redis 内部会把MaxRedirects0重映射为 3-1 表示禁用重试因此即使 YAML 缺省该字段实际生效值也是 3源码中的 flag 注册注释也明确说明暴露 3 只是让--help反映有效默认值。min_idle_conns用于维持连接池中的最小空闲连接数避免按需建立新连接的开销。Memcached 缓存连接默认值Tempo 3.1 改变了 memcached 缓存客户端的默认连接行为使连接池在请求突发之间保持温热。如果你不使用 memcached 缓存则无需操作对应 PR 7671。具体变化默认max_idle_conns从16提高到100。建议将其设置得高于你的峰值并行请求数使连接在突发之间保持温热。空闲连接默认不再被关闭。新的min_idle_conns_headroom_percentage默认值为-1即保持空闲连接不关闭设置为0可恢复旧行为——关闭空闲超过两分钟的连接。新增connect_timeout用于独立约束建连时间。当未设置0s时回退到timeout的值。这些默认值会提高每个 memcached 服务器的稳态打开连接数。若要保留旧行为请在缓存配置中显式设置max_idle_conns: 16和min_idle_conns_headroom_percentage: 0。源码佐证位于 pkg/cache/memcached_client.goConnectTimeout time.Duration \yaml:connect_timeout注释明确如果为 0 则使用 Timeoutmax-idle-conns的 flag 默认值已注册为100帮助文本同样建议设置高于峰值并行请求数以保持连接温热。Trace by ID 查询分片随 block 数量扩展Trace by ID 查询会被切分为跨 block 范围的多个 job。Tempo 3.1 新增query_frontend.trace_by_id.blocks_per_shard设置目标是将每个 job 覆盖一定数量的 block而非使用固定 job 数其默认值为30且只要非零就优先于旧的query_shards设置对应 PR 7105。此前query_shards默认50会将每次 trace by ID 查询切分为相同的固定 job 数无论租户有多少 block。该值必须针对一个 cell 中最大的租户来调优导致较小的租户每个 job 只覆盖太少的 block而且当摄取量变化时必须重新评估。设置了blocks_per_shard后Tempo 会根据租户当前的 block 数动态计算分片数job 数随租户规模自动伸缩同一 cell 内不同大小的租户都能获得合适的切分。计算出的分片数永远不会超过query_frontend.max_outstanding_per_tenant因此不会压垮查询队列。这一变更影响所有为自身工作负载调优过query_shards的用户以及依赖 trace by ID 查询产生固定、可预测子查询数量的用户例如在仪表盘、告警或容量规划中。如需保留旧的固定分片数行为设置blocks_per_shard: 0回退到query_shardsquery_frontend: trace_by_id: blocks_per_shard: 0 query_shards: 50源码验证modules/frontend/config.go 中QueryShards默认值为50BlocksPerShard默认值为30注释说明该值来自对生产部署的调研是大多数工作负载的良好默认。而 modules/frontend/traceid_sharder.go 中的分片逻辑为当cfg.BlocksPerShard 0时走固定QueryShards路径否则按numBlockShards ceil(len(blocklist) / BlocksPerShard)从实时 blocklist 动态推导分片边界。升级到 Tempo 3.0Tempo 3.0 是一个主要版本major release用分离读写路径的新架构取代了基于 ingester 的旧架构block-builder、live-store 和后端调度器backend scheduler取代了 ingester 与 compactor。新架构的详细描述见 Tempo 架构参考。注意vParquet3已弃用。Tempo 3.x 仍可读取已有的 vParquet3 block因此无需转换它们。但如果你的存储配置指定了vParquet3请将写入格式改为vParquet4或更高版本具体见 block 格式版本说明。迁移路径取决于你的部署模式单体模式Monolithic先更新配置移除ingester、ingester_client、compactor和metrics_generator_client配置块再升级二进制。不需要 Kafka。分步说明见 Migrate a monolithic deployment参考单体配置见 Deploy Tempo locally。微服务模式Microservices需要一个兼容 Kafka 的系统。将 Tempo 3.0 与现有 2.x 部署并行部署切换流量然后退役 2.x。完整流程见 Migrate from Tempo 2.x to 3.0。你可以使用tempo-cli migrate config命令自动化配置迁移它会移除过时的配置块并为微服务模式添加所需的ingest配置。升级到 Tempo 3.0 时还需注意以下破坏性变更无降级路径不支持从 3.0 降级到 2.x。可扩展单体模式SSB移除scalable-single-binarytarget 不再可用。请改用微服务或单体target: all模式见部署模式。部署清单更新更新 Helm、Tanka 等部署清单加入新组件与 Kafka 基础设施。Legacy overrides 默认禁用Tempo 3.0 现在检测到主配置或按租户 overrides 文件中存在 legacy扁平、unscoped格式的 overrides 时会拒绝启动对应 PR 6741。解决办法是迁移到 scopeddefaults格式推荐或临时选择重新启用旧格式。方案一迁移到 scoped 格式将 overrides 从 legacy 扁平格式转换为 scopeddefaults格式。例如迁移前legacyoverrides: ingestion_rate_limit_bytes: 20000000 ingestion_burst_size_bytes: 20000000 max_bytes_per_trace: 30000000 max_traces_per_user: 100000迁移后scopedoverrides: defaults: ingestion: rate_limit_bytes: 20000000 burst_size_bytes: 20000000 max_traces_per_user: 100000 global: max_bytes_per_trace: 30000000你可以使用 Tempo CLI 自动化迁移参考tempo-cli migrate overrides-config命令。legacy 与 scoped 格式间的完整字段映射可参考 Tempo 2.3 版本说明中的 overrides 模块配置变更章节。方案二临时重新启用在 overrides 配置块中设置enable_legacy_overrides: true或通过 CLI 传-config.enable-legacy-overridestrue。启动时以及每次加载按租户 overrides 时会记录弃用警告。这只是临时的逃生舱escape hatchlegacy overrides 将在未来版本中移除。overrides: enable_legacy_overrides: true源码验证modules/overrides/config.go 中定义了EnableLegacyOverrides bool \yaml:enable_legacy_overrides其 flag 默认值为false帮助文本明确指出默认禁用将在未来版本移除。mem-ballast-size-mbs标志移除-mem-ballast-size-mbs命令行标志已被移除。Go 1.19 及更高版本使用GOMEMLIMIT替代该标志不再需要对应 PR 6403。如果你的部署脚本、Helm values 或 Tanka/Jsonnet 配置传入了-mem-ballast-size-mbs请将其删除——否则 Tempo 会因无法识别的标志而启动失败。Metrics-generator 配置变更metrics-generator 的 gRPC 端点与推送路径已被移除。在 Tempo 3.0 中metrics-generator 直接从 Kafka 消费数据而不再通过 gRPC 从 distributor 接收 span对应 PR 6618。如果你的配置中包含顶层metrics_generator_client块可以安全地将其移除。Tempo 3.0 会忽略该块它已被弃用将在未来版本移除。Block 配置集中到storage.trace.blockblock-builder 与 live-store 的 block 和 WAL 配置现在始终来自storage.trace.block。各模块独立的 block 配置字段已被移除对应 PR 6647。如果你的配置在block_builder.block或live_store.block_config下设置了version、parquet_dedicated_columns、parquet_row_group_size_bytes等 block 级选项请将它们移到storage.trace.block。迁移前block_builder: block: version: vParquet5 parquet_dedicated_columns: - { scope: resource, name: service.name, type: string } live_store: block_config: version: vParquet5 parquet_dedicated_columns: - { scope: resource, name: service.name, type: string }迁移后storage: trace: block: version: vParquet5 parquet_dedicated_columns: - { scope: resource, name: service.name, type: string }partition_ring_live_store移除Tempo 3.0 移除了顶层partition_ring_live_store设置。Tempo 现在使用统一的 partition ring不再需要该配置开关对应 PR 6981。如果你的 2.x 配置仍包含该字段请在 3.0 升级前或升级期间将其移除。迁移前partition_ring_live_store: true迁移后# 删除 partition_ring_live_storeLive-store 与查询默认值降低多个 live-store 与 query-frontend 设置的默认值已调低以产生更小的 WAL block、更早释放已完成 block并使 metrics 查询后端边界与 search 对齐。设置旧默认值新默认值live_store.flush_check_period10s5slive_store.max_block_duration30m30slive_store.max_block_bytes100 MiB50 MiBlive_store.complete_block_timeout1h20mquery_frontend.metrics.query_backend_after30m15m如果你在配置中显式设置了这些值则无需任何操作。Fail-on-high-lag 默认启用Tempo 3.0 现在会在 live-store 无法保证完整结果时直接让 search 与 metrics 请求失败而不是返回部分结果。live_store.fail_on_high_lag设置默认值为true此前为false。当 live-store 的 Kafka lag 与查询时间范围重叠时请求返回错误而不是静默返回不完整结果——以可用性换取正确性对应 PR 7210。该变更同时将query_frontend.query_end_cutoff设置为30s此前为0从查询中排除最近 30 秒的数据以避免不完整结果。该 cutoff 必须小于query_frontend.search.query_backend_after。要恢复旧行为继续返回部分结果设置live_store: fail_on_high_lag: false要检测出现 lag 的请求请监控tempo_live_store_lagged_requests_total指标详见 Manage trace ingestion 文档。Ingester 移除ingester 模块被完全移除。所有与 ingester 相关的配置字段、CLI 标志、告警与仪表盘面板都必须从你的部署中删除。写入路径现在由 block-builder 与 live-store 处理。被移除的配置段ingester、ingester_client、compactor、metrics_generator_client。ingest.enabled字段也被移除但ingest块本身在微服务模式下仍然必需例如ingest.kafka。分步迁移说明见 Migrate from Tempo 2.x to 3.0。Compactor 移除与 CLI 标志变更compactor 组件与v2block 编码被移除。压缩compaction现在由后端调度器与 worker 处理它们会集中跟踪 job 进度并自动重新调度失败的 job。请从部署中删除所有与 compactor 相关的配置、告警与仪表盘面板。以下tempo-cli命令也因针对v2格式而被移除list block、list index、view index、gen index、gen bloom。compaction CLI 标志去掉了重复的compaction.前缀。请更新配置中的以下标志compaction.compaction.block-retention→compaction.block-retentioncompaction.compaction.max-objects-per-block→compaction.max-objects-per-blockcompaction.compaction.max-block-bytes→compaction.max-block-bytescompaction.compaction.compaction-window→compaction.compaction-windowRetryInfo默认启用distributor.retry_after_on_resource_exhausted设置现在默认值为5s此前为0。当 distributor 返回ResourceExhausted错误时OTLP 客户端会收到重试提示对应 PR 7088。如需在集群范围禁用将值设为0如需为单个租户禁用设置按租户 overrideingestion.retry_info_enabled: false。TraceQL 数组匹配变更TraceQL AST 优化改变了数组属性上!与!~运算符的语义。!现在表示NOT IN此前为CONTAINS NOT EQUAL!~现在表示MATCH NONE此前为CONTAINS NON-MATCH。正则操作数必须是 string 或 string 数组类型对应 PR 6353。如果你有依赖旧行为的查询可通过查询提示skip_optimizationtrue禁用该优化。其他破坏性变更alltarget 现在与 3.0 兼容scalable-single-binarytarget 被移除。见部署模式PR 6283。OpenCensus receiver 被移除请迁移到 OTLPPR 6523。SpanMetricsSummary被移除querier 代码被简化PR 6496、PR 6510。querier.query_live_store配置被移除PR 7048。query_frontend.search.query_ingesters_until被移除改为使用query_frontend.search.query_backend_after见 query-frontend 组件参考PR 6507。tempo-cli query search命令不再接受不带时区的时间戳例如2024-01-01T00:00:00。请使用 RFC3339 格式例如2024-01-01T00:00:00Z或相对时间例如now-1h见 Tempo CLI 文档PR 6458。Tempo 3.0 升级到 Go 1.26.2PR 6443。升级执行建议与验证清单综合上述变更一次完整的升级通常遵循如下流程备份与评估在非生产环境搭建与生产一致的部署用statusAPI 导出当前配置确认是否存在将被移除的配置段ingester、compactor、metrics_generator_client、partition_ring_live_store、query_ingesters_until等。配置迁移单体模式直接更新配置并升级二进制微服务模式先在 2.x 旁并行部署 3.0配置好 Kafka 与ingest块后再切换流量。可运行tempo-cli migrate config见 cmd-migrate-config.go与tempo-cli migrate overrides-config见 cmd-migrate-overrides-config.go自动完成大部分机械性改写。缓存配置核对若使用 Redis确认single_node: true是否必需、TLS 块是否为 dskit 风格、idle_timeout/max_connection_age是否已改名若使用 memcached评估新默认max_idle_conns: 100与空闲连接不关闭对连接数的稳态影响。查询行为验证确认 trace by ID 分片策略是否符合预期blocks_per_shard默认30设为0回退固定query_shards确认fail_on_high_lag: true与query_end_cutoff: 30s带来的正确性优先语义是否被告警规则所感知。清理遗留物删除-mem-ballast-size-mbs标志、compactor 相关告警/面板、OpenCensus receiver以及所有指向已移除tempo-cli命令的脚本调用。总结从 2.x 到 3.0/3.1 的升级本质上是架构换代而非单纯版本迭代ingester 与 compactor 退出历史舞台读写路径由 block-builder、live-store 与后端调度器接管缓存客户端、overrides 格式、查询分片策略同步重构。升级文档upgrade.md与本文列出的 YAML 前后对照、默认值变更表格及源码证据构成了一个可逐步执行的迁移清单。无论选择单体模式直接替换还是微服务模式并行切换核心原则一致先迁移配置、再验证查询语义、最后在非生产环境充分演练才能确保升级过程中的数据正确性与服务可用性。赞分享后端可观测性链路追踪【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址https://gitcode.com/GitHub_Trending/tempo1/tempo点击查看免费下载相关推荐Grafana Tempo 3.0 升级全指南架构重构、破坏性变更与配置迁移实战Grafana Tempo 3.0 升级全指南架构重构、破坏性变更与配置迁移实战本文以仓库根目录下的 CHANGELOG.md https://link.g后端可观测性链路追踪Arduino ESP32 核心 2.x 到 3.0 迁移指南API 破坏性变更与升级实战Arduino ESP32 核心 2.x 到 3.0 迁移指南API 破坏性变更与升级实战导读本指南以 docs/en/migration_guides/嵌入式物联网驱动开发Loki 升级指南从 2.x 到 4.0 的配置变更、破坏性改动与迁移实践Loki 升级指南从 2.x 到 4.0 的配置变更、破坏性改动与迁移实践 LokiGrafana Loki持续保持向后兼容的努力但每次版本迭代仍会伴随可观测性日志分析后端微服务对象存储云原生上一篇Three-BVH-CSG重新定义WebGL三维建模的布尔运算性能边界下一篇开源项目的生死抉择当技术热情遭遇法律边界创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Grafana Tempo 升级实战指南：从 2.x 迁移到 3.0 / 3.1 的破坏性变更与配置迁移

相关推荐

3DES加解密源码解析：密钥处理、ECB/CBC模式与PKCS7填充实战

数据采集选型实战：API与全托管平台如何权衡？

Windows 上安装 Claude Code 实战：环境配置与高频报错排查

更多资讯

RAG查询路由技术：原理、实现与优化策略

GraalVM Native Image Build Report 完整指南：生成、逐区解析与动态访问诊断

10 分钟用 TaoToken 跑通 MCP Filesystem 服务

uBlock Origin 快速上手：免费浏览器广告拦截，3 分钟装完即用

Phoenix Context 与 Schema 测试完全指南：DataCase、SQL Sandbox 与测试生成机制

GPT Computer Assistant：三步跑通 Python AI 智能体助手（支持本地大模型）

今日更新

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？