4. Tempo 配置基础：配置文件结构与核心配置项详解

Grafana Tempo 的配置体系围绕 tempo.yaml 单一配置文件展开，所有组件（distributor、ingester、querier、compactor）共享同一份配置，通过 target 参数决定进程启动的角色。理解配置文件的层级结构和核心配置项，是进行查询优化与索引调优的前提。

4.1 配置文件结构（tempo.yaml）

tempo.yaml 采用 YAML 格式，顶层键对应 Tempo 的架构组件和通用基础设施。以下为典型结构概览：

以下是一个最小化 tempo.yaml 骨架示例：

server:
  http_listen_port: 3200
  grpc_listen_port: 9095

distributor:
  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: 0.0.0.0:4317

ingester:
  lifecycler:
    ring:
      kvstore:
        store: memberlist

querier:
  frontend_worker:
    frontend_address: 127.0.0.1:9095

compactor:
  compaction:
    block_retention: 336h

storage:
  trace:
    backend: s3
    s3:
      bucket: tempo-traces
      endpoint: s3.amazonaws.com
    pool:
      max_workers: 100
    block:
      bloom_filter_false_positive: 0.05
      encoding: zstd
    wal:
      path: /var/tempo/wal

4.2 核心配置项详解

4.2.1 storage 配置：索引与存储引擎

storage 是 Tempo 性能调优的核心，直接影响查询延迟和存储成本。它包含后端适配器、块索引、WAL 和缓存策略。

存储后端配置示例（S3）：

storage:
  trace:
    backend: s3
    s3:
      bucket: tempo-traces
      endpoint: s3.us-east-1.amazonaws.com
      access_key: ${AWS_ACCESS_KEY_ID}
      secret_key: ${AWS_SECRET_ACCESS_KEY}
    block:
      bloom_filter_false_positive: 0.01
      encoding: zstd
      index_downsample_bytes: 2097152  # 2MB
    wal:
      path: /var/tempo/wal
      encoding: zstd

4.2.2 distributor 配置：数据入口与负载均衡

Distributor 负责接收来自 OpenTelemetry Collector、Jaeger Agent 等客户端的 Span 数据，并根据一致性哈希将数据路由到对应的 Ingester。

4.2.3 ingester 配置：内存块与刷盘策略

Ingester 是 Tempo 的写入路径核心，负责将 Span 数据暂存在内存中，按时间或大小切分成块（block），最终刷写到后端存储。

ingester:
  lifecycler:
    ring:
      kvstore:
        store: memberlist
      replication_factor: 3
  trace_idle_period: 10s        # 无新 Span 时，块最大等待时间
  max_block_duration: 30m       # 块最大生命周期
  max_block_bytes: 500_000_000  # 块最大字节数（500MB）
  flush_check_period: 30s       # 刷盘检查周期

• trace_idle_period：如果某个 trace 在 10 秒内没有新 Span 到达，则关闭当前块。减小此值可加速数据可见性，但会增加块数量。
• max_block_duration：块从创建到刷盘的最大时间，默认 30 分钟。增大可减少块数量，但会延迟数据可查询时间。
• max_block_bytes：块大小上限，达到此值立即刷盘。建议根据 Span 平均大小和内存预算调整。

4.2.4 querier 配置：查询并行与 TraceQL 执行

Querier 负责处理来自 Query Frontend 的查询请求，扫描后端存储中的块，执行 TraceQL 过滤并返回结果。

4.2.5 compactor 配置：块合并与数据生命周期

Compactor 是 Tempo 的后台维护组件，负责将后端存储中的小块合并成大块，执行数据去重，并根据 retention 策略清理过期数据。

compactor:
  compaction:
    block_retention: 336h               # 数据保留时间（14天）
    compacted_block_retention: 1h       # 合并后源块保留时间
    compaction_window: 1h               # 合并时间窗口
    max_block_bytes: 1073741824         # 合并后最大块大小（1GB）
    max_compaction_objects: 1000000     # 单次合并最大对象数
  ring:
    kvstore:
      store: memberlist

• block_retention：数据保留时长，超过此时间的块会被 Compactor 删除。支持 h（小时）、d（天）单位。
• compaction_window：合并操作的时间窗口，默认 1 小时。窗口越小，合并越频繁，但可能产生过多小块。
• max_block_bytes：合并后块的最大字节数。增大可减少块数量，但会延长单次合并时间。

4.3 组件协作关系图

以下 SVG 展示了 Tempo 各组件通过 tempo.yaml 配置驱动的数据流与协作关系：

4.4 配置优先级与覆盖机制

Tempo 支持多层级配置覆盖，理解优先级有助于快速定位问题：

1. 默认值：Tempo 内置的出厂配置，适用于快速启动。
2. tempo.yaml：主配置文件，覆盖默认值。
3. 环境变量：以 _ 分隔的路径格式覆盖，例如 STORAGE_TRACE_BACKEND=local。
4. 命令行参数：通过 -config.file 指定配置文件路径，或使用 -storage.trace.backend 直接覆盖。
5. Overrides 模块：通过 overrides 配置块实现租户级覆盖，优先级最高。

4.5 配置验证与调试

在将配置部署到生产环境前，建议使用以下方法验证：

• tempo -config.file=tempo.yaml -verify-config：Tempo 内置配置验证命令，检查语法和必填项。
• tempo -config.file=tempo.yaml -print-config：打印最终生效的配置（包含所有覆盖），用于调试。
• 日志级别调整：在 server.log_level 设置为 debug，观察启动时各组件加载的配置值。

以下 SVG 展示了配置验证与生效流程：

4.6 生产环境配置清单

以下清单总结了生产环境部署 Tempo 时，tempo.yaml 中必须关注的核心配置项：