Tempo 3.1 release: new features for Kafka, TraceQL metrics updates, trace redaction, and more

Tempo 3.1 为基于 Kafka 的数据摄入增加了多项社区贡献的改进，新增了保护连接、降低数据传输成本、支持更多 Kafka 兼容后端等选项。

[TLS 及更多 SASL 机制](https://grafana.com/blog/tempo-3-1-release-all-the-latest-features/#tls-and-more-sasl-mechanisms)

Tempo 3.0 将微服务模式摄入迁移到 Kafka，其自带的客户端虽然能进行身份验证，但仅支持 SASL PLAIN 且只能通过非加密连接。由于没有 TLS 设置，要求 TLS 的代理会拒绝连接。Tempo 3.1 新增了 TLS 支持及四种机制：SCRAM-SHA-256、SCRAM-SHA-512、OAUTHBEARER 和 AWS_MSK_IAM。

ingest:
  kafka:
    address: kafka.example.com:9093
    topic: tempo-traces
    sasl_mechanism: SCRAM-SHA-512
    sasl_username: ${KAFKA_USERNAME}
    sasl_password: ${KAFKA_PASSWORD}
    tls_enabled: true
    tls_ca_path: /etc/tempo/kafka-ca.pem
    tls_cert_path: /etc/tempo/kafka-client.crt   # 可选，用于 mTLS
    tls_key_path: /etc/tempo/kafka-client.key    # 可选，用于 mTLS

传递 -config.expand-env=true 以展开环境变量。

感谢 @heytrav 的贡献。了解更多请参见 PR 和 配置身份验证和 TLS 文档。

[机架感知获取](https://grafana.com/blog/tempo-3-1-release-all-the-latest-features/#rack-aware-fetching)

Tempo 始终从分区领导者获取数据，无论其所在位置。当领导者位于其他可用区时，每次读取都会跨越可用区边界，云服务商会为此收取传输费用。

新 client_rack 选项通过启用机架感知获取（KIP-392）帮助降低这些成本，使消费者可以从本区域的副本读取数据：

ingest:
  kafka:
    client_rack: us-east-1a

这是一个读取端设置，适用于 block-builders、live-stores 和 metrics-generators，但不适用于将记录写入 Kafka 的 distributor。您的代理需要配置机架 ID 才能生效。

感谢 @KyriosGN0 的贡献。了解更多请参见 PR 和 摄入配置 文档。

[可配置的生产者压缩](https://grafana.com/blog/tempo-3-1-release-all-the-latest-features/#configurable-producer-compression)

Tempo 的 distributor 会压缩写入 Kafka 的每一批数据，但在 3.1 版本之前，编解码器不可配置。除非后端仅支持一种编解码器（例如 Azure Event Hubs 支持 Kafka 协议但仅接受 gzip），否则这会限制其作为 Tempo 后端的使用。

新的 producer_compression 选项允许你从 none、gzip、snappy、lz4 或 zstd 中选择：

ingest:
  kafka:
    producer_compression: gzip

结合上述的 TLS 支持，这个选项使 Event Hubs 成为 Tempo 的可用 Kafka 后端。如果你未设置 producer_compression，Kafka 客户端将默认使用 snappy。如果后端不支持 snappy，请将 producer_compression 设置为受支持的算法，或设置为 none 以禁用压缩。

感谢 @fleighton 的贡献。了解更多内容，请参阅 PR 和 ingest 配置 文档。

[保护敏感数据：使用 TraceQL 查询擦除追踪](https://grafana.com/blog/tempo-3-1-release-all-the-latest-features/#protect-sensitive-data-redact-traces-with-a-trace-ql-query)

在 Tempo 3.0 中，我们添加了追踪擦除功能，允许你永久删除敏感数据（如电子邮件地址、认证令牌或意外出现在跨度属性中的账户号码），而无需等待保留期过期。但 tempo-cli redact 仅接受追踪 ID，因此你必须列举所有受影响的追踪。敏感数据通常会出现在特定代码路径的流量中，这可能比你实际能列出的追踪数量更多。任何遗漏的追踪仍然存储在对象存储中，并且可能被查询。

现在，使用 Tempo 3.1，你可以通过 TraceQL 查询进行擦除：

tempo-cli redact \
  --tenant=<TENANT_ID> \
  --query '{span.attribute = "<leaked PII>"}' \
  --dry-run \
  <SCHEDULER_ADDRESS>:<GRPC_PORT>

如上所示，建议首先使用 --dry-run。Tempo 会评估查询并计算将删除的内容，而不会修改任何块。该命令会打印批次 ID 和创建的作业数量。作业数量以及匹配或删除的追踪数量是按租户划分的指标，可以在 后端工作仪表板 的“擦除”行中查看，该仪表板随 Tempo 的监控混合包一起提供。当计数与预期匹配后，运行相同命令但去掉 --dry-run 参数以重写块。此操作不可逆。

由于错误的查询会永久删除你本不想删除的数据，我们目前故意限制接受的语法范围：仅允许使用 resource.* 和 span.* 属性的等值比较的单个 spanset 过滤器，通过 && 和 || 组合。超出此范围的内容在提交作业时会被拒绝。我们将继续改进此功能。

如果你知道需要擦除数据的时间范围，可以使用它来更快更高效地运行作业。这对于高流量安装非常重要，因为在执行擦除时，Tempo 会暂停租户的压缩操作。使用 --start 和 --end 参数，它们接受 now、类似 now-7d 的相对偏移量或 RFC3339 时间戳。压缩操作会在运行之间进行追赶。

注意： 仅在您的单元中每个调度器和工作节点都至少运行 Tempo 3.1 时，才使用 --start 和 --end 参数一次。较旧版本的工作节点会忽略时间窗口，并会移除其接收到的每个数据块中的所有查询匹配项，无论时间戳如何，且不会报错，也无法恢复数据。

如需了解更多内容，请参阅查询选择器 PR、时间范围 PR 以及 红action追踪 文档，以了解完整的查询语法和约束条件。

查询追踪指标，实现更高的准确性、灵活性和速度：TraceQL 指标更新

在 Tempo 3.0 中，TraceQL 指标已正式发布，允许您直接从追踪数据中查询即席指标。这使得您更容易回答有关分布式系统中性能、错误率和服务行为的问题。

随着 3.1 版本的发布，我们推出了多项更新，使 TraceQL 指标更加灵活、高效，并在处理采样追踪数据时更加准确。

采样感知指标查询

假设您在追踪数据到达 Tempo 之前采样了 50% 的追踪数据。如果您对某个服务运行 rate() 查询，您将只看到实际流量的一半，因为 Tempo 仅统计通过采样环节的追踪跨度。

这在使用 自适应追踪 和其他 尾部采样 配置时特别有用，这些配置下不同服务的采样率可能不同。通过采样感知查询，TraceQL 指标可以考虑这些差异，并更准确地反映底层流量。

在 Tempo 3.1 中，您可以使用新的实验性 with(extrapolate=true) 提示，在查询时修正采样问题：

{ } | rate() with(extrapolate=true)

%3Aquality(90)%2F&w=3840&q=75)

对 50% 采样追踪数据执行相同查询，左侧未使用提示，右侧使用了提示。两个图表形状相同，但左侧 y 轴最高为 4，右侧 y 轴最高为 8。

实现 OpenTelemetry 的 概率采样规范 的采样器（目前仍处于开发阶段，并非所有语言都支持），会将采样率记录在 span 的 tracestate 字段中。该提示会读取该采样率并据此调整 span 的统计值。在 50% 采样率下，每个存储的 span 会被计算为 2 个，因此匹配 1,000 个 span 的查询会返回 2,000。未记录采样率的 span 会被计算为 1 个，这意味着部分采用是安全的：如果只有两个服务启用了采样，其他服务的统计数据不会受到影响。

不会向你的数据块写入新内容。tracestate 本就已与每个 span 一同存储，不使用该提示的查询不会读取该字段。如果你已在 metrics-generator 中通过设置 enable_tracestate_span_multiplier（我们在 Tempo 3.0 中新增了该功能）修正了采样影响，查询路径会以相同方式读取采样率，因此即席查询与你的预聚合 tempo_spanmetrics_* 系列数据结果一致。

外推功能适用于 rate、count_over_time、sum_over_time、avg_over_time、histogram_over_time、quantile_over_time 和 compare。它不适用于 min_over_time 或 max_over_time，因为采样不会改变你实际观测到的最小值或最大值。

注意： 此提示为实验性功能，需要 vParquet4 数据块或更高版本。

了解更多内容，请参阅PR 和 TraceQL 指标函数 文档。

将指标查询与算术运算结合

你从追踪中推导出的许多指标需要结合两个指标查询，而不仅仅是运行一个查询。一个常见示例是错误率。传统上，TraceQL 可以分别测量错误和总流量，但无法将二者相除，因此你必须运行两个查询，并在 Grafana 中使用数学表达式进行相除。

在 Tempo 3.1 中，你可以在 TraceQL 中直接编写除法运算。+、-、* 和 / 运算符可以在两个指标查询之间使用，因此错误率只需一个查询：

({ status = error } | rate() by (resource.service.name)) / ({ } | rate() by (resource.service.name))

%3Aquality(90)%2F&w=3840&q=75)

两侧都使用 by (resource.service.name) 的相同除法，因此每个服务都有自己的错误率。相比之下，使用查询 ({status=error} | rate() by (resource.service.name)) / ({} | rate()) 时，仅分子按服务分组，而分母是基于所有数据计算的。

如果你对查询进行分组，只有当两个序列的标签集完全匹配时才会合并，而没有标签的一侧会广播到另一侧的所有序列。

你可以将 with(extrapolate=true) 与算术运算结合使用。表达式末尾的提示适用于两个子查询：

({ status = error } | rate()) / ({ } | rate()) with(extrapolate=true)

该提示必须放在末尾。将 with(...) 放在子查询内部是语法错误。

如需了解更多内容，请参阅算术 PR、标量 PR、算术表达式 文档以及 七月社区电话会议。

默认情况下更快的指标查询

指标查询也更快了：我们看到简单的查询速度接近原来的两倍。我们在 Tempo 3.0 中作为实验性功能引入的仅限跨度的获取路径，现在在 vParquet5 块中默认启用，而 Tempo 3.1 正是使用这种格式进行写入。

现在，不需要完整跟踪结构的查询会处理单个跨度而非整个跟踪，这降低了延迟和内存使用。在一个预热测试中，启用仅限跨度获取的 { } | rate() 完成时间仅为禁用该功能时的一半多一点。你无需更改查询即可使用此功能，如果需要，也可以按租户或按查询禁用。

如需了解更多内容，请参阅 PR 和 更快的读取路径 文档。

指标生成器的增强功能

指标生成器 是 Tempo 的一个可选组件，它从摄入的跨度中派生指标，为你提供 RED（速率/错误/持续时间）指标和服务图，这些图显示了服务之间的关系。在这里，我们介绍了 Tempo 3.1 中对指标生成器的一些改进，但请参阅 变更日志 和 发布说明 以获取完整列表。

查看为什么你的服务地图缺少边

Tempo 通过将客户端和服务器跨度配对来构建服务图边。当一侧从未到达时，边会过期并在你的地图上留下空白，你无法区分不存在的连接和 Tempo 无法匹配的连接。

在 Tempo 3.1 中，我们向过期边的计数器添加了 unmatched_span_kind 标签，这样你可以看到哪一侧丢失了。例如，许多标记为 SPAN_KIND_SERVER 的过期边指向永远不会解析为节点的服务器到服务器的监控。

要了解更多内容，请参阅PR、服务图文档以及过期边故障排除文档。

从更新的OTel语义约定中识别`db.system.name`

OpenTelemetry 语义约定 v1.30.0将db.system属性重命名为db.system.name。仅发出新名称的仪器不再被识别为数据库调用，因此在SDK升级后，这些节点会从您的服务地图中消失，且没有错误提示。

Tempo 3.1接受这两种属性来识别数据库请求和命名虚拟节点。当跨度同时包含这两种属性时，db.system具有优先权，因此升级SDK不会重命名仪表板和警报已经指向的节点。

感谢@iamrajiv的贡献。要了解更多内容，请参阅PR和数据库名称属性文档。

削减每条跨度的指标生成器成本

生成器处理您摄入的每个跨度，因此每条跨度的工作量决定了运行成本的下限。构建标签集占用了大量工作量。

现在，span-metrics和service-graphs处理器从注册表借用池化标签缓冲区，而不是每次分配新的缓冲区，我们的稳态service-graphs基准测试报告每次操作零分配。指标名称、标签和值保持不变，因此您在仪表板上不会看到任何差异，只需不再需要为生成器的CPU和内存进行配置。

要了解更多内容，请参阅跨度指标PR和服务图PR。

使用跨度修剪使大型追踪更易于阅读

单个用户请求可以生成许多跨度。如果您的应用程序在该请求背后运行了100个几乎相同的数据库查询，每个查询都会成为自己的跨度，最终您会得到1个根跨度和100个看起来相同的数据库跨度。这种追踪更难阅读，请求的查询越多，情况越糟糕。

在Tempo 3.1中，trace-by-ID v2端点将每组相似的叶跨度折叠成一个汇总跨度，该跨度携带aggregation.span_count以及被替换跨度的最小、最大、平均和总持续时间。在上面的示例中，您将得到2个跨度而不是101个，响应相应地更小。只有当跨度的名称、类型、状态和父名称匹配时才会分组，因此错误永远不会与成功合并。此操作在读取时发生，因此不会有任何内容离开存储。

按查询请求：

GET /api/v2/traces/<traceID>?span_pruning=true

在您的 Tempo 配置中将 span_pruning_enabled_by_default 设置为 true，这样就不需要在每次请求中传递 span_pruning 参数：

query_frontend:
  trace_by_id:
    span_pruning_enabled_by_default: true

这同样适用于 Grafana UI 和 Tempo MCP 服务器的 get-trace 工具，目前两者均未发送该参数。请求中显式指定的 span_pruning 仍具有优先级，因此需要完整追踪信息的调用方始终可以请求获取。您还可以按租户设置该默认值。

我们还为 trace-by-ID v2 端点添加了 TraceQL 过滤器支持。它在 q 参数上接受一个单个 spanset 过滤器，因此您可以获取一条追踪并仅返回匹配的跨度，而不是全部跨度。这些跨度默认会单独返回；添加 keep_hierarchy=true，您还可以获取每个匹配项到根节点的祖先路径。

GET /api/v2/traces/<traceID>?q={ span.http.status_code = 500 }&keep_hierarchy=true

gcx CLI 正在更新以支持 gcx traces get 的两个参数：--prune 用于修剪，--filter 用于查询。

注意： 跨度修剪功能尚处于实验阶段。span_pruning 参数、其行为和响应格式可能会在未来版本中发生变化。

如需了解更多内容，请参阅 trace pruning[](https://github.com/grafana/tempo/pull/7566)PR、过滤器 PR、请求参数的[](https://grafana.com/docs/tempo/latest/api_docs/?pg=tempo-3-1-release-all-the-latest-features&plcmt=in-text#query-v2)Query V2 API 文档、[](https://grafana.com/docs/tempo/latest/configuration/?pg=tempo-3-1-release-all-the-latest-features&plcmt=in-text#query-frontend)query-frontend 配置文档，以及 八月社区会议。

让 AI 的追踪对比更高效

有时您需要比较两个追踪：某个端点在部署后变慢了，您有一个部署前的追踪和一个部署后的追踪，或者相同的请求对一个调用方成功而对另一个失败。无论哪种情况，手动比较都需要在两个追踪中滚动查找发生变化、出现或消失的跨度。

在 Tempo 3.1 中，您可以使用追踪差异功能将两个追踪 ID 发送到 query-frontend，获取差异结果，而不是拉取两个追踪并自行比较。这也会为 LLM 创建更小的上下文窗口，使 AI 驱动的调查更快、更便宜：

POST /api/v2/traces/diff

{
  "base": { "traceId": "<BASE_TRACE_ID>" },
  "compare": { "traceId": "<COMPARE_TRACE_ID>" }
}

默认情况下，您会得到一个跨度级别的补丁，列出每个已添加、删除或修改的跨度。部分追踪会被拒绝，因为不完整的追踪中缺失的跨度会看起来像是被删除的跨度。

你也可以要求生成摘要而不是补丁。它会报告跟踪延迟、错误和跨度数量是上升还是下降，结构是否发生变化，涉及哪些服务，并为发生变动的服务提供毫秒级的差异值。它会告诉你每个数值的变化方向，而不是判断这是否是回归问题。一个变快的跟踪可能只是更早地出现了故障。

摘要还能捕捉到补丁过滤掉的漂移现象。当某个服务中的每个跨度都略微变慢时，单个跨度可能未超过单个跨度的容忍阈值，但该服务的总跨度持续时间确实超过了，因此该服务仍会被标记为已更改。

你可以使用多种工具来获取跟踪差异。gcx CLI 通过实验性命令 gcx traces diff 封装了 API，使你能够直接在终端中比较两个 ID，而无需自行获取任一跟踪：

gcx traces diff --context prod -d <DATASOURCE_UID> <BASE_TRACE_ID> <COMPARE_TRACE_ID>

tempo-cli experimental traces-diff 则用于比较两个本地跟踪 JSON 文件，这在你已导出文件时非常方便。默认情况下它会输出补丁，你可以使用 --format 参数获取摘要。我们在 2.9 版本中新增的 Tempo MCP 服务器 现在包含了一个 traces-diff 工具，会优先返回摘要，这样连接到 Tempo 的 AI 助手无需每次都拉取大补丁就能获得可用答案。

注意： 此接口为实验性功能。未来版本中请求和响应格式可能会发生变化。

如需了解更多内容，请参阅 API PR、CLI PR、MCP PR、traces diff API 文档、experimental traces diff Tempo CLI 文档、gcx traces diff 参考文档以及 Compare traces Tempo MCP 文档。

查询性能提升和内存使用降低：vParquet5 现在是默认的块格式

Tempo 使用 Apache Parquet 列式块格式存储跟踪，并持续优化布局以提高性能和效率。我们在 Tempo 2.10 版本中引入 了 vParquet5 作为可选格式，而在 3.1 版本中，它将成为默认格式。

vParquet5 还为 Parquet 列的配置方式提供了更多自定义选项。现在可以在资源、跨度和事件级别分别设置两倍数量的专用字符串列、整数支持，以及非常长或高基数的字符串（称为“blobs”）。充分利用这一功能的最佳方式是使用新的 tempo-cli 命令 suggest columns。它会分析你的数据并告知你最佳布局，同时方便你复制粘贴输出结果到 Tempo 配置中。

要了解更多关于 vParquet5 带来功能的信息，请参阅专用列文档和 Tempo 2.10 版本发布博文的vParquet5 部分。你也可以查看PR和Apache Parquet 块格式文档。

如何了解更多

要查看 Tempo 3.1 的完整改进列表、错误修复和重大变更，请参考发布说明和变更日志。升级前，请查阅升级你的 Tempo 安装以了解需要操作的变更。

如果你想了解更多的 Tempo 新闻，请加入我们的Grafana Labs 社区 Slack频道 #tempo，在我们的社区论坛发帖提问，或参加我们每月的Tempo 社区会议。我们在那里见！