文档 Grafana Tempo 设置 升级

升级您的 Tempo 安装

您可以将 Tempo 安装升级到下一个版本。但是，任何版本都可能包含破坏性更改。我们建议在非生产环境中测试这些更改，然后才推广到生产环境。

升级过程因每个版本而异，具体取决于后续版本中的更改。

本升级指南适用于本地安装，不适用于 Grafana Cloud。

有关任何版本的详细信息，请参阅发行说明。

升级到 Tempo 2.7

升级到 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"

每个 span set 的最大 span 数

默认启用新的 max_spans_per_span_set 限制，并设置为 100。将其设置为 0 可恢复旧行为（无限制）。否则，超出配置最大值的 spans 将被丢弃。（#4275）

复制

query_frontend:
  search:
      max_spans_per_span_set: 0

Tempo Serverless 已弃用

Tempo Serverless 已正式弃用，并将在即将发布的版本中移除。请准备将任何 Serverless 工作流迁移到其他部署方式。（#4017，文档）

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

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

TraceQL 中的 Regex 匹配器现在使用 Prometheus 的快速 regexp 完全锚定。例如，span.foo =~ "bar" 被解释为 span.foo =~ "^bar$"。请相应地调整现有查询。（#4329）

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

从 OpenTracing 迁移到 OpenTelemetry

use_otel_tracer 选项已移除。通过标准的 OpenTelemetry 环境变量配置您的 spans。对于 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 压缩设置。

有关如何启用 gRPC 压缩的说明，请参阅gRPC 压缩配置了解更多信息。

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

其他升级注意事项

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

升级到 Tempo 2.6

Tempo 2.6 在升级时有几个注意事项：

• TraceQL 指标的操作变更
• vParquet4 现在是默认的 block 格式
• 已更新、移除或重命名的参数

有关完整的更改列表，请参阅 Tempo 2.6 CHANGELOG。

TraceQL 指标的操作变更

由于无法达到 RF3 去重性能目标，我们已将 TraceQL 指标更改为 RF1（复制因子 1）模式。这需要对查询 TraceQL 指标进行一些操作更改。

TraceQL 指标仍被视为实验性功能，但我们希望在生产化完整的 RF1 写读路径后尽快将其标记为 GA。[PRs 3628, 3691, 3723, 3995]

对于近期数据

必须启用 local-blocks processor 才能开始使用诸如 { } | rate() 的指标查询。如果未启用，指标查询将失败并显示错误 localblocks processor not found。可以在每个租户或所有租户中启用 local-blocks processor。

• 在 per-tenant overrides 中按租户配置

  yaml 复制

    overrides:
      'tenantID':
        metrics_generator_processors:
          - local-blocks

• 默认情况下，在主配置中为所有租户配置

  yaml 复制

  overrides:
    defaults:
      metrics_generator:
        processors: [local-blocks]

添加此配置以对所有 spans（而不仅仅是服务器 spans）运行 TraceQL 指标查询

yaml 复制

metrics_generator:
  processor:
    local_blocks:
      filter_server_spans: false

对于历史数据

要对历史数据运行指标查询，您必须配置 local-blocks processor 将 RF1 blocks 刷新到对象存储

yaml 复制

metrics_generator:
  processor:
    local_blocks:
      flush_to_storage: true

过渡到 vParquet4

vParquet4 格式现在是默认的 block 格式。它已可用于生产环境，我们强烈建议切换到它以提高查询性能。[PR 3810]

升级到 Tempo 2.6 会修改 Parquet block 格式。从 2.5 升级到 2.6 时，您无需对 Parquet 进行任何操作。如果您使用了 vParquet2 或 vParquet3，您的所有旧 blocks 都将保留，并且可以由 Tempo 2.6 读取。Tempo 2.6 默认创建 vParquet4 blocks，从而启用新的 TraceQL 功能。

尽管您可以在 Tempo 2.6 中使用 vParquet2 或 vParquet3，但 vParquet4 只能在 Tempo 2.5 及更高版本中使用。如果您在 2.5 中使用 vParquet4，则需要升级到 Tempo 2.6 才能使用新的 TraceQL 功能。

您还可以使用 tempo-cli analyse blocks 命令查询 vParquet4 blocks。PR 3868]。有关详细信息，请参阅 Tempo CLI 文档。

有关升级的信息，请参阅升级到 Tempo 2.6 和选择不同的块格式。

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

tempo-query 是一个独立服务器

从 Tempo 2.6.1 开始，tempo-query 不再是带有 grpcPlugin 的 Jaeger 实例。它现在是一个独立服务器。默认在 0.0.0.0:7777 提供 Jaeger 的 gRPC API。[PR 3840]

升级到 Tempo 2.5

Tempo 2.5 在升级时有几个注意事项：

• Docker 镜像以新的 UID 运行
• 对 vParquet 格式的支持已移除
• 实验性的 vParquet4 block 格式
• 已移除的配置参数

有关完整的更改、增强和错误修复列表，请参阅 Tempo 2.5 CHANGELOG。

Docker 镜像以新的 UID 运行

官方 Docker 镜像中的 Tempo 进程以前以 root 用户运行。现在，Tempo 进程在 Docker 镜像中以 UID 10001 运行。（官方 Docker 镜像）

维护磁盘上文件的 ingester 和 metrics generator 等组件在没有干预的情况下无法干净启动。新用户 10001 将无法访问 root 创建的旧文件。

/var/tempo 的所有权已从 root:root 更改为 tempo:tempo，UID/GID 为 10001。

ingester 和 metrics-generator statefulsets 可能需要运行 chown 来更改所有权才能正常启动。

请参阅 PR 2265 查看 init 容器的 Jsonnet 示例。

如果您使用带有 chart 中设置的默认安全上下文的 Helm chart，此更改不会影响您。所有数据都应该已经归 Tempo 用户所有。UID 不会影响 Helm chart 用户。

对 vParquet 格式的支持已移除

Tempo 2.5 中已移除原始的 vParquet 格式 has been removed。无法直接从 Tempo 2.1 升级到 Tempo 2.5。您需要升级到中间版本，并等待旧的 vParquet blocks 超出保留期后再升级到 2.5。PR 3663]

vParquet(1) 将不再被识别为有效的编码，并且任何剩余的 vParquet(1) blocks 将不可读。

使用历史默认设置运行的安装应该不需要任何更改，因为默认设置已在几个版本中迁移。存储设置固定为 vParquet 的安装必须运行配置为 vParquet2 或更高版本的先前版本，直到所有现有的 vParquet(1) blocks 已过期并从后端删除，否则升级到此版本后将遇到读取错误。

实验性的 vParquet4 block 格式

vParquet4 block 格式是查询 links、events 和 arrays 所必需的，并且相对于以前的格式提高了查询性能。vParquet4 将成为下一个版本中的默认 block 格式。[ PR 3368]

虽然您可以使用 vParquet4，但请记住它是实验性的。如果您选择使用 vParquet4，然后选择恢复到 vParquet3，则 vParquet4 blocks 将无法由 vParquet3 读取。

要尝试 vParquet4，请参阅选择块格式。

已移除的配置参数

其他注意事项

• 更新到 OTLP 1.3.0 移除了 OTLP receivers 中已弃用的 InstrumentationLibrary 和 InstrumentationLibrarySpan。[PR 3649]
• 移除了在多租户 trace id 查找中添加租户的功能。[PR 3522]

升级到 Tempo 2.4

Tempo 2.4 在升级时有几个注意事项：

• vParquet3 现在是默认的后端
• 缓存配置已重构
• 已更新、移除和重命名的配置参数

有关完整的更改、增强和错误修复列表，请参阅 Tempo 2.4 CHANGELOG。

过渡到 vParquet3 作为默认 block 格式

vParquet3 格式现在是默认的 block 格式。它已可用于生产环境，我们强烈建议切换到它以提高查询性能和专用属性列。

升级到 Tempo 2.4 会修改 Parquet block 格式。虽然您可以在 Tempo 2.3 中使用 vParquet2 或 vParquet3，但 Tempo 2.4 只能使用 vParquet3。

在此版本中，我们第一个版本的 Parquet 后端 vParquet 已被弃用。Tempo 2.4 仍然可以读取 vParquet1 blocks。但是，如果手动配置它们，Tempo 将会出错退出。[ PR 3377]

有关更改 vParquet 版本的信息，请参阅选择不同的块格式。

缓存配置已重构

主要的缓存重构允许您配置多个基于角色的缓存。[ PR 3166] 此更改导致多个字段被弃用（请参阅旧配置）。

这些字段都已迁移到顶层的 cache: 字段。

有关配置的详细信息，请参阅 Cache 部分。

旧的配置块如下所示：

yaml 复制

storage:
  trace:
    cache:
    search:
      cache_control:
    background_cache:
    memcached:
    redis:

使用新配置，您可以创建缓存列表，使用 redis 或 memcached 集群进行配置，然后定义数据类型和角色。

简单配置示例

yaml 复制

cache:
  caches:
  - memcached:
      host: <some memcached cluster>
    roles:
    - bloom
    - parquet-footer
  - memcached:
      host: <some memcached cluster>
    roles:
    - frontend-search

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

现在，如果批次仅包含 trace_too_large 和 max_live_traces 错误，distributor 会返回 200。被丢弃的 spans 数量仍然反映在 tempo_discarded_spans_total metrics 中。

升级到 Tempo 2.3

Tempo 2.3 在升级时有几个注意事项：

• vParquet3 作为稳定、可用于生产的 block 格式可用
• 使用 Azure SDK v2 的配置选项
• Overrides 模块配置中的新 defaults block
• 多个配置参数已重命名或移除。

有关完整的更改、增强和错误修复列表，请参阅 Tempo 2.3 CHANGELOG。

可用于生产的 vParquet3 block 格式

vParquet3 提高了查询性能和专用属性列。

使用专用属性列需要此 block 格式。

虽然 vParquet2 仍然是 Tempo 2.3 的默认后端，但 vParquet3 可作为一个稳定选项使用。两者都适用于 Tempo 2.3。

升级到 Tempo 2.3 不会修改 Parquet block 格式。

推荐的更新流程

1. 将 Tempo 安装升级到版本 2.3，并保持使用 vParquet2。
2. 验证升级是否稳定并按预期运行。如果您发现任何问题，可以降级到版本 2.2，并且数据仍然可读。
3. 将 block 格式更改为 vParquet3.

如果您在使用新 block 格式的步骤 3 中发现任何问题，可以降级到 vParquet2。您的所有数据在 Tempo 2.3 中仍然可读。但是，如果您有 vParquet3 blocks 并且必须降级到 Tempo 2.2，则会丢失数据。

使用 Azure SDK v2

如果您使用 Azure 存储，我们建议使用 v2 SDK，即 azure-sdk-for-go。您可以使用 use_v2_sdk 配置选项进行切换。

有关详细信息，请参阅存储 block 配置示例文档。

Overrides 模块配置中的新 defaults block

Overrides 模块有一个新的 defaults block，用于配置全局或按租户设置。Overrides 格式现在包括缩进语法的更改。有关详细信息，请阅读Overrides 配置文档。

您还可以使用 Tempo CLI 迁移配置。请参阅tempo-cli 文档。

旧的配置块如下所示：

yaml 复制

overrides:
  ingestion_rate_strategy: local
  ingestion_rate_limit_bytes: 12345
  ingestion_burst_size_bytes: 67890
  max_search_duration: 17s
  forwarders: ['foo']
  metrics_generator_processors: [service-graphs, span-metrics]

新的配置块如下所示：

yaml 复制

overrides:
  defaults:
    ingestion:
      rate_strategy: local
      rate_limit_bytes: 12345
      burst_size_bytes: 67890
    read:
      max_search_duration: 17s
    forwarders: ['foo']
    metrics_generator:
      processors: [service-graphs, span-metrics]

已移除或重命名的配置参数

升级到 Tempo 2.2

Tempo 2.2 在升级时有几个注意事项：

• vParquet2 现在是默认的 block 格式
• 多个配置参数已重命名或移除。

有关完整的更改、增强和错误修复列表，请参阅 Tempo 2.2 CHANGELOG。

默认 block 格式更改为 vParquet2

尽管不是破坏性更改，但默认升级到 Tempo 2.2 会将 Tempo 的 block 格式更改为 vParquet2。

要保持使用先前的 block 格式，请阅读Parquet 配置文档。我们强烈建议尽快升级到 vParquet2，因为这是在 TraceQL 查询中使用结构运算符所必需的，并且可以提高查询性能，尤其是在使用 duration intrinsic 的查询中。

更新的 JSonnet 支持 metrics-generator 的 statefulset

Tempo 2.2 更新了 microservices JSonnet，以支持 metrics_generator 组件的 statefulset。

为了支持新的 processor，metrics-generator 已从 deployment 转换为带有 PVC 的 statefulset。这需要手动干预才能成功迁移并避免停机。请注意，目前 JSonnet 将同时管理 deployment 和 statefulset 一段时间，之后我们将从该仓库中删除 deployment，您将需要删除用户端对 tempo_metrics_generator_deployment 的引用，并删除 deployment 本身。

请参阅 PR 获取无缝迁移说明。[PRs 2533, 2467]

已移除或重命名的配置参数

以下字段已被移除或重命名。

query_frontend:
  tolerate_failed_blocks: 

storage:
  trace:
  s3:
  insecure_skip_verify: true  // renamed to tls_insecure_skip_verify

升级到 Tempo 2.1

Tempo 2.1 在升级时有两个主要注意事项：

• 已移除对 v2 block 搜索的支持
• 指标名称的破坏性更改

有关其他增强功能的详细信息，请阅读Tempo 2.1 发行说明。

移除对 v2 block 搜索的支持

用户无法再搜索 v2 格式的 blocks。只有 Parquet 格式支持搜索。这些搜索配置选项已从 overrides 部分移除：

复制

overrides:
  max_search_bytes_per_trace:
  search_tags_allow_list:
  search_tags_deny_list:

以下 metrics 配置也已移除：

复制

tempo_ingester_trace_search_bytes_discarded_total

从 Tempo 1.x 到 2.1 保持搜索的升级路径

移除对 v2 block 搜索的支持意味着如果您直接从 1.9 升级到 2.1，将无法搜索 v2 blocks。为避免这种情况，请先升级到 2.0，因为 2.0 支持搜索 v2 和 vParquet blocks。您可以在 Tempo 从传入 traces 创建新的 vParquet blocks 的同时，让旧的 v2 blocks 逐渐老化。一旦所有 v2 blocks 已删除且仅剩 vParquet 格式 blocks，您就可以升级到 Tempo 2.1。您的所有 blocks 都将可搜索。

执行搜索时不再缓存 Parquet 文件。

Tempo 暴露的指标名称的破坏性更改

Tempo 在其 /metrics endpoint 上暴露的所有以前缀 cortex_ 开头的 Prometheus 指标现在已重命名，改为前缀 tempo_。（PR 2204）

Tempo 现在包含 SLO 指标，用于计算在可配置时间范围内返回的查询数量。（PR 2008）

已移除 query_frontend_result_metrics_inspected_bytes 指标，转而使用 query_frontend_bytes_processed_per_second。

从 Tempo 1.5 升级到 2.0

Tempo 2.0 是 Tempo 开发中的一个重要里程碑。在规划升级时，请考虑以下因素：

• 破坏性更改
  • 重命名、移除和移动的配置将在下文介绍。
  • TempoRequestErrors 告警已从 mixin 中移除。依赖此告警的 Jsonnet 用户应将其复制到自己的环境中。
• 建议
  • 默认值已更改。这些更新是否与您的安装相关？
  • 需要在 Grafana 中启用 TraceQL 编辑器才能使用查询编辑器。
  • 使用默认配置的 Tempo 2.0 资源要求已更改。

一旦升级到 Tempo 2.0，将无法降级。

检查 Tempo 安装资源分配

Parquet 提供了更快的搜索功能，并且启用 TraceQL 需要它。但是，Tempo 安装需要额外的 CPU 和内存资源才能高效使用 Parquet。由于构建列式 blocks 需要额外工作，Parquet 的成本更高，操作人员应该预期运行 Tempo 2.0 集群所需的资源至少增加 1.5 倍。大多数用户发现这些额外资源相对于 TraceQL 的附加功能以及将 traces 存储在开放格式中带来的好处而言微不足道。

您可以使用Parquet 配置文档中提供的说明继续使用先前的 v2 block 格式。Tempo 在可预见的未来将继续支持在 v2 格式上进行 trace id 查找。

在 Grafana 中启用 TraceQL

TraceQL 在 Tempo 2.0 中默认启用。TraceQL 查询编辑器需要 Grafana 9.3.2 及更高版本。

TraceQL 查询编辑器在 Grafana 9.3.2 中处于 Beta 阶段，需要使用 traceqlEditor 功能标志启用。

检查已移除和重命名选项的配置

下表描述了已移除或重命名的参数。

已移除并替换

query_frontend:
  query_shards:

querier:
  query_timeout:

ingester:
  use_flatbuffer_search:

已重命名

以下 compactor 配置参数已重命名。

compaction:
  chunk_size_bytes:

compaction:
  flush_size_bytes:

compaction:
  iterator_buffer_size:

以下 storage 配置参数已重命名。

wal:
  encoding:

block:
  index_downsample_bytes:

block:
  index_page_size_bytes:

block:
  encoding:

block:
  row_group_size_bytes:

Azure Storage 配置部分现在使用带有下划线 (_) 的 snake_case 命名，而不是带有破折号 (-)。Azure Storage 配置中使用 snake_case 的示例：

yaml 复制

# config.yaml
storage:
  trace:
    azure:
      storage_account_name:
      storage_account_key:
      container_name: