文档 Grafana Tempo 发布说明 V2.7

2.7 版本发布说明

Tempo 团队很高兴宣布 Tempo 2.7 版本发布。

此版本提供以下功能：

• 能够基于自定义标签精确跟踪摄入流量并归因成本
• 一系列显着提升 Tempo 性能并减少整体资源占用的增强功能。
• 新的 TraceQL 功能
• TraceQL 指标改进

阅读Tempo 2.7 博客文章以了解更多关于这些改进的示例和详细信息。

这些发布说明重点介绍了最重要的功能和错误修复。有关完整列表，请参阅Tempo 变更日志。

功能和增强

Tempo 2.7 中最重要的功能和增强功能如下所示。

跟踪摄入流量并归因成本

这项新功能允许租户通过利用自定义标签精确测量其摄入追踪数据的成本并进行归因。此功能提供了比现有基于大小的指标更准确的替代方案，满足了对详细成本归因和计费透明度日益增长的需求。

现代组织越来越依赖分布式追踪进行可观测性，但协调与不同团队、服务或部门相关的成本可能具有挑战性。现有的基于大小的指标不够准确，会遗漏非 Span 数据，并可能导致计数不足或过度。新的使用跟踪功能通过公平地分割资源级别数据并提供高达 99% 的准确性来克服这些问题，非常适用于成本核算。

与之前的方法不同，这项新功能精确计算了 Distributor 中每一字节的追踪数据——它是 Tempo 中唯一拥有原始 payload 的组件。一个新的 API 端点 /usage_metrics 公开了每个租户的摄入数据和成本归因指标，并且可以通过每个租户的配置进行控制。

此功能旨在作为更广泛使用跟踪功能的基础，额外的跟踪器将允许组织测量和报告一系列使用指标。（#4162）

有关更多信息，请参阅使用指标文档。

主要的性能和内存使用改进

我们很高兴宣布一系列显着提升 Tempo 性能并减少整体资源占用的增强功能。

更好地拒绝大追踪：Ingester 现在重用生成器代码，以便更好地检测和拒绝超大追踪。这一更改使追踪摄入更可靠，并防止容量过载。此外，新增的两个指标 tempo_metrics_generator_live_trace_bytes 和 tempo_ingester_live_trace_bytes 提供了更深入的每个租户字节使用情况可见性。（#4365）

减少分配：我们优化了 query-frontend 处理传入流量的方式，以消除在查询需求较低时不必要的分配。作为这些改进的一部分，querier_forget_delay 配置选项已被移除，因为它不再具有实际用途。（#3996）此版本还通过改进 prealloc 行为来减少 ingester 的工作集。它还添加了可调整的 prealloc 环境变量 PREALLOC_BKT_SIZE, PREALLOC_NUM_BUCKETS, PREALLOC_MIN_BUCKET，以及用于观察和调整 prealloc 行为的指标 tempo_ingester_prealloc_miss_bytes_total。（#4344，#4369）

更快的标签查找和 Collector 操作：多项优化（#4100、#4104、#4109）使标签查找和 Collector 任务响应更快，尤其是在进行去重值搜索时。此外，在 Ingester 中为已完成块启用磁盘缓存显着降低了查询延迟并减少了整体 I/O 开销。（#4069）

减少非 Querier 组件中的 goroutines：非 Querier 组件的简化设计减少了 goroutines 的总数，使得 Tempo 即使在高追踪量下也能更高效且更易于扩展。（#4484）

新的 TraceQL 功能

Tempo 2.7 新增功能，TraceQL 现在允许您查询Instrumentation scope 字段（#3967），让您可以根据追踪的插桩位置和方式进行过滤和探索。

我们扩展了 TraceQL，使其能够自动从数组值中收集匹配项（#3867），从而更轻松地解析包含属性数组的 Span。

得益于多项优化（#4114、#4163、#4438），查询速度显着提升。无论您运行标准查询还是高级过滤器，您都应该看到显着的加速。

Tempo 现在使用 Prometheus 的“快速 regex”引擎来加速基于正则表达式的过滤（#4329）。作为此次更新的一部分，所有正则表达式匹配现在都完全锚定。这项重大更改意味着 span.foo =~ "bar" 将被评估为 span.foo =~ "^bar$"。请相应更新所有受影响的查询。

查询改进

在 API v2 查询中，即使追踪超出最大字节限制，Tempo 现在也可以返回部分追踪（#3941）。这确保您仍然可以检索和检查大型追踪中的有用片段，以帮助调试。有关更多信息，请参阅query v2 API 端点文档。

TraceQL 指标改进（实验性）

在 TraceQL 指标中，我们添加了一个新的 avg_over_time 函数（#4073），以帮助您计算基于追踪的指标在指定时间范围内的平均值，从而更轻松地发现趋势和异常。

Tempo 现在支持 min_over_time（#3975）和 max_over_time（#4065）查询，让您在分析追踪数据中的最小值或最大值时更具灵活性。

有关 TraceQL 指标的更多信息，请参阅TraceQL 指标函数。

其他增强和改进

此版本还包含以下值得关注的更新。

2.7.1

• 默认对 Tempo 内部的所有 gRPC 通信使用 snappy 压缩。我们认为这在资源使用和网络流量之间取得了良好的平衡。有关替代方案的讨论，请参阅此讨论帖。（#4696）

2.7.0

• metrics-generator (metrics-generator) 为失败的 flush 尝试引入了宽松的 100 次限制（#4254），以防止对损坏块的持续重试。新增的指标也跟踪这些 flush 失败，提供了更好的可见性，帮助您快速诊断摄入过程中可能出现的问题。
• 对于 Span 指标（span metrics），Span multiplier 现在也从资源属性中获取其值（#4210）。这使得可以使用服务或环境配置来调整和修正指标，从而确保更准确的数据报告。
• tempo-cli 现在支持在单个命令中删除多个追踪 ID，从而加快管理任务并简化清理操作。（#4266）
• 一个可选日志 log_discarded_spans 跟踪 Tempo 丢弃的 Span。这提高了数据摄入工作流程的可见性，并帮助您快速诊断任何丢弃的 Span。（#3957）
• 您现在可以对标签和标签值查找施加限制，以防止在大规模部署中出现失控查询，并确保更流畅的用户体验。（#4320）
• 标签和标签值端点新增了吞吐量和与 SLO 相关的指标。直接从 Tempo 的内置监控中获取有关查询性能和可靠性的更深入洞察。（#4148）
• Tempo 现在在其 /api/status/buildinfo 端点中公开 SemVer 版本，提供清晰的版本可见性，对于云部署和自动化管道特别有用。（#4110）

升级注意事项

当升级到 Tempo 2.7 时，请注意这些注意事项和重大更改。

OpenTelemetry Collector Receiver 默认监听 localhost

此更改后，OpenTelemetry Collector Receiver 默认绑定到 localhost 而非 0.0.0.0。在 Docker 或其他容器环境中运行的 Tempo 安装必须更新其监听地址以继续接收数据。（#4465）

大多数 Tempo 安装使用默认配置的 Receiver

yaml 复制

distributor:
  receivers:
    otlp:
      protocols:
        grpc:
        http:

以前这运行良好，因为 Receiver 默认分别绑定到 0.0.0.0:4317 和 0.0.0.0:4318。随着替换未指定地址的更改，Receiver 现在默认绑定到 localhost:4317 和 localhost:4318。

因此，连接到运行在 Docker 容器中的 Tempo 将不再工作。

要解决此问题，您需要明确指定要绑定的地址。例如，如果 Tempo 在主机名为 tempo 的容器中运行，这应该可以工作

yaml 复制

# ...
        http:
          endpoint: "tempo:4318"

您仍然可以显式绑定到 0.0.0.0，但这存在潜在的安全风险

yaml 复制

# ...
        http:
          endpoint: "0.0.0.0:4318"

Tempo Serverless 弃用

Tempo Serverless 现已正式弃用，并将在后续版本中移除。请准备将所有 Serverless 工作流迁移到其他部署方式。（#4017，文档）

此版本对 Serverless 没有更改。但是，您需要在下一个版本发布之前移除这些配置。

TraceQL 中锚定正则表达式匹配器

TraceQL 现在使用 Prometheus 的“快速 regex”引擎来加速基于正则表达式的过滤（#4329）。作为此次更新的一部分，所有正则表达式匹配现在都完全锚定。这项重大更改意味着 span.foo =~ "bar" 将被评估为 span.foo =~ "^bar$"。请相应更新所有受影响的查询。

有关更多信息，请参阅TraceQL 比较运算符文档。

从 OpenTracing 迁移到 OpenTelemetry

此版本移除了 use_otel_tracer 选项。请通过标准的 OpenTelemetry 环境变量配置您的 Span。对于 Jaeger 导出，设置 OTEL_TRACES_EXPORTER=jaeger。有关更多信息，请参阅OpenTelemetry 文档。（#3646）

添加、更新、移除或重命名的配置参数

gRPC 压缩设置为 snappy

Tempo 2.7.1 将所有组件之间的 gRPC 压缩设置为 snappy。使用 snappy 为组件间的压缩提供了一种平衡方法，适用于大多数安装。

如果您偏好 CPU/内存与带宽之间不同的平衡，可以考虑禁用压缩或使用 zstd。

有关替代方案的讨论，请参阅此讨论帖。（#4696）。

gRPC 压缩已禁用

出于性能原因，Tempo 2.7.0 版本在 querier 和 distributor 中禁用了 gRPC 压缩。（#4429）。我们的基准测试表明，不进行压缩时，querier 和 distributor 使用的 CPU 和内存更少。

Tempo 2.7.1 将内部组件的默认值更改为 snappy。

如果您注意到网络流量增加或出现问题，请检查 gRPC 压缩设置。您可以使用 snappy 启用 gRPC 压缩

yaml 复制

  ingester_client:
      grpc_client_config:
          grpc_compression: "snappy"
  metrics_generator_client:
      grpc_client_config:
          grpc_compression: "snappy"
  querier:
      frontend_worker:
          grpc_client_config:
              grpc_compression: "snappy"

有关更多信息，请参阅gRPC 压缩配置。

其他升级注意事项

• Tempo CLI 现在默认指向 /api/v2/traces 端点。如果您仍然依赖较旧的 /api/traces 端点，请使用 --v1 标志。（#4127）
• 如果您已在每个租户的覆盖配置或全局 Tempo 配置中设置了 X-Scope-OrgID 头，现在会优先使用它，Tempo 不会覆盖。如果您之前依赖于自动注入，这可能会改变行为。（#4021）
• AWS Lambda 构建输出从 main 更改为 bootstrap。按照AWS 迁移步骤进行操作，以确保您的 Lambda 函数继续工作。（#3852）

错误修复

有关完整列表，请参阅Tempo CHANGELOG。

2.7.2

• 修复当 querier 在 ingester 和 generator 的结果被 marshalled 到 proto 时修改这些结果导致的罕见 panic。此错误还会通过在结果未就绪时返回不完整的结果来影响最近追踪数据的查询正确性。（#4790）

2.7.0

• 将 invalid_utf8 添加到 Span 指标将丢弃 Span 的原因列表中。（#4293）我们现在可以捕获追踪数据中不能用作有效指标标签的值。如果您想按 foo 获取 Span 指标，但 foo 中包含非法 Prom 更改，则不会写入这些指标。
• Metrics-generators：在停止摄入之前正确地从环中移除，以减少发布期间的丢弃。（#4101）
• 在 gRPC 流中正确处理 400 Bad Request 和 404 Not Found。（#4144）
• 在 gRPC 流中正确处理 Authorization 头。（#4419）
• 修复 TraceQL 指标在最近数据和后端数据之间的截止点的时间范围处理。（#4257）
• 修复 TraceQL 指标的 exemplar 值的一些问题。（#4366，#4404）
• 在 tempo-cli 选项中利用 S3Pass 和 S3User 参数，这些参数之前在代码中未使用。（#4259）