Grafana Tempo 1.4 版本发布解读：服务端指标、trace 查询性能优化与升级指南

Grafana Tempo 1.4 版本发布解读：服务端指标、trace 查询性能优化与升级指南

【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo

Tempo 1.4 是 Grafana Tempo 分布式追踪后端发展历程中的一个关键里程碑，其头号特性Server-side metrics（服务端指标）让用户可以直接从 traces 生成指标，从而对应用性能随时间的演进获得更深洞察。本文以官方 V1.4 发布说明（v1-4.md）为核心骨架，结合当前仓库源码与配置文档，系统梳理 1.4 版本的功能增强、破坏性变更、升级注意事项与缺陷修复，帮助读者在升级前完成评估与准备，并理解这些能力在代码层面的落地方式。

一、功能与增强（Features and enhancements）

1. 服务端指标（Server-side metrics）：Tempo 1.4 的头号特性

Tempo 1.4 将服务端指标生成器（metrics-generator）作为本次发布的重点特性推出。其核心思路是：不再需要部署额外的摄取管道，Tempo 自身即可在服务端从传入的 trace 数据中派生并输出指标（例如服务图 Service Graphs、Span 指标），再通过 remote write 写入 Prometheus 等时序存储，从而为运维与开发提供"按时间维度观察应用性能"的能力。

当前仓库中该特性的文档体系位于 metrics-from-traces/metrics-generator，配套实现则集中在 modules/generator 目录，其子目录processor（含 service graphs、span metrics 等处理器）、registry（指标聚合注册表）与storage（remote write 存储）共同构成了 metrics-generator 的完整链路。读者可以顺此路径深入了解各处理器的配置与输出指标定义。

开启该特性后，metrics-generator 会消费 Kafka 上的 trace 数据并聚合输出指标。当前仓库的 generator_kafka.go 与配套测试 generator_kafka_test.go 展示了其在 Kafka 模式下的启动与数据消费流程，可作为源码级参考。

2. trace 查询接口新增start/end参数

1.4 为/api/traces/{traceID}接口新增了start和end两个查询参数，允许调用方按时间范围检索 trace。这一改动带来的直接收益是：查询时只需命中后端（backend）上时间窗口内的部分 block，从而显著提升查询效率、降低后端 I/O 压力（对应上游 PR 1388）。

在源码层面，该参数已沉淀为当前仓库的标准 URL 参数。见 pkg/api/http.go 中的常量定义：

urlParamStart = "start" urlParamEnd = "end"

而前端处理器在收到/api/traces/{traceID}请求时，也会先对start、end参数进行校验，再继续后续查询，见 modules/frontend/traceid_handlers.go 中newTraceIDHandler/newTraceIDV2Handler对api.ParseTraceByIDRequest(req)的调用。实际使用中，start与end均以 Unix 秒为单位传递，配合traceID路径参数即可限定查询窗口。

3. 防止超大 trace 拖垮实例：max_bytes_per_trace保护体系

为保护单实例不被超大 trace 拖垮，1.4 围绕已有的max_bytes_per_trace配置参数补充了多层防护（对应上游 PR 1317、PR 1318）。该参数本质上是一条租户级限制（limit），用于限制单个 trace 允许的字节上限，超出部分会被丢弃。

在当前仓库中，max_bytes_per_trace定义于 modules/overrides/config.go：

MaxBytesPerTrace int `yaml:"max_bytes_per_trace,omitempty" json:"max_bytes_per_trace,omitempty"`

同时在 modules/overrides/config_legacy.go 中保留了旧版配置的兼容字段。它属于 overrides 体系中的运行时限制之一，可以按租户（tenant）粒度覆盖。典型配置示例（摘自 modules/frontend/docs/config-reference.md）：

overrides: defaults: max_bytes_per_trace: 5000000 # 单个 trace 的字节上限

1.4 新增的防护全部以该参数为"开关"：当 trace 超过阈值时，相关 span 会以trace_too_large_to_compact等丢弃原因被计数（tempo_discarded_spans_total），从而避免超大 trace 在 ingest、compact 等环节消耗过多内存与 CPU。1.4.1 的修复中重新填充了compaction_objects_combined_total与tempo_discarded_spans_total{reason="trace_too_large_to_compact"}两个指标，正是这套保护体系的观测配套。

4. "Hedge everything"：全面对冲外部端点请求

Tempo 团队用他们最钟爱的方案——hedging（对冲请求）——来提升后端搜索吞吐。对冲的核心思想是：当一次请求超过设定延迟仍未返回时，主动发起一个重复请求，谁先返回用谁，从而削平长尾延迟。

1.4 将这一能力推广到 querier 的外部端点（external endpoints），配置形如：

querier: search: external_hedge_requests_at: 5s external_hedge_requests_up_to: 3

参数含义（与存储后端对冲参数一致，参见 configuration/_index.md）：

• hedge_requests_at：发起重复请求前的延迟，建议设置为后端请求 p99 延迟量级，默认0（禁用）；
• hedge_requests_up_to：允许发出的最大请求数（含原始请求），默认2，需在hedge_requests_at已设置的前提下生效。

从当前仓库的配置演进看，hedging 已成为 Tempo 查询链路的标配能力：各存储后端（GCS、S3、Azure）均支持hedge_requests_at/hedge_requests_up_to对冲配置（见 configuration/_index.md 中各 backend 配置块），querier 侧也保留了对冲相关选项的继承与默认值调整（上游后续版本将外部端点对冲默认值从4s/3放宽到8s/2，并在 CHANGELOG 中有记录）。hedging 在 querier 节点上效果最明显，因为它直接作用于读路径延迟；对其他组件影响较小。

二、升级注意事项（Upgrade considerations）

升级到 Tempo v1.4 前，请确认以下破坏性变更，并按顺序规划滚动发布。

1. 新摄取端点：先滚动 ingester，再滚动 distributor（PR 1227）

1.4 新增了一个摄取端点，用于支撑更快的搜索以及 block 上正确的 start/end 时间。为保证发布期间不中断服务：

• 先滚动所有 ingester，再滚动 distributor，否则可能造成停机；
• 滚动期间 ingester 会消耗明显更多资源，应提前扩容，或对流入流量进行强限流；
• 当所有 distributor 与 ingester 都完成滚动后，性能恢复正常。官方内部观测到滚动期间 ingester 的 CPU 负载约为平时的1.5 倍。

2. querier 配置项迁移：search子块整合（PR 1350）

为支持对外部端点的 hedging，部分 querier 选项发生了位置迁移。升级时必须同步调整配置结构，否则旧字段会被忽略。迁移前后对照如下：

迁移前（旧结构）：

querier: search_query_timeout: 30s search_external_endpoints: [] search_prefer_self: 2

迁移后（新结构，1.4 起生效）：

querier: search: query_timeout: 30s prefer_self: 2 external_endpoints: []

这一"扁平字段收拢为子块"的结构在当前仓库的 querier 配置中已成定型：见 modules/querier/config.go，Config内含Search SearchConfig yaml:"search"，其中：

type SearchConfig struct { QueryTimeout time.Duration `yaml:"query_timeout"` }

且默认值为cfg.Search.QueryTimeout = 30 * time.Second（见 modules/querier/config.go），与发布说明中的示例一致。可见search子块是后续版本长期沿用的配置形态。

3. 移除 CLI 参数tempo-search-retention-duration（PR 1297）

1.4 更新了 vulture 对全后端搜索的测试方式，并因此移除了 CLI 参数tempo-search-retention-duration。若现有部署脚本或 systemd unit 中仍引用该参数，升级前务必清理，否则启动会报"未知参数"类错误。

三、缺陷修复（Bug fixes）

1.4.0 修复项

其中PR 1314与本版新增的start/end查询参数相互呼应：block 边界时间从"摄取时间"修正为"trace 实际时间"后，基于时间窗口的 block 裁剪才能命中正确的数据子集，这也是 1.4 查询效率提升的底层前提之一。

1.4.1 修复项

这些修复大多可以在当前仓库中找到对应实现与测试痕迹：tempo_discarded_spans_total的丢弃原因枚举与计数逻辑位于 modules/overrides/discarded_spans.go，distributor 的 forwarder/queue 实现位于 modules/distributor/forwarder 与 modules/distributor/queue，可作为深入排查的入口。

四、升级建议与验证路径

综合以上变更，向 Tempo 1.4 升级的推荐操作清单如下：

1. 改配置：将 querier 中search_query_timeout/search_external_endpoints/search_prefer_self扁平字段迁移到querier.search子块；清理启动脚本中的tempo-search-retention-duration。
2. 定版本内滚动顺序：先滚动全部 ingester，并在此期间为其预留约 1.5 倍 CPU 余量或启用限流；随后再滚动 distributor，最后滚动其余组件。
3. 按需开启新能力：
   • 服务端指标：参考 metrics-from-traces/metrics-generator/_index.md 启用 metrics-generator 并配置 remote write；
   • 时间窗口查询：调用/api/traces/{traceID}?start=<unix_sec>&end=<unix_sec>限定查询范围；
   • 超大 trace 防护：在 overrides 中设置合理的max_bytes_per_trace；
   • 对冲：为 querier 外部端点或存储后端配置hedge_requests_at/hedge_requests_up_to以削平长尾延迟。
4. 验证观测指标：升级后重点确认compaction_objects_combined_total、tempo_discarded_spans_total、hedged roundtrips 相关指标是否按预期计数，以判断摄取、压缩与查询链路是否健康。

Tempo 1.4 以"服务端指标 + 查询效率 + 稳定性"三条主线完成了一次承上启下的迭代：它既通过 metrics-generator 打开了"从 trace 到指标"的产品形态，也通过 start/end 参数与 block 时间语义修正为后续查询优化奠定基础。上文涉及的源码路径（modules/generator、modules/querier/config.go、modules/overrides/config.go、pkg/api/http.go）均可作为理解这些能力的起点，供读者按需深入。

【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo