4. Tempo 配置详解：配置文件结构与关键参数调优

Grafana Tempo 的配置体系围绕其微服务架构设计，每个核心组件（Distributor、Ingester、Querier、Compactor、Storage）均有独立的配置块。理解这些配置项及其调优逻辑，是定位分布式追踪性能瓶颈的基础。

4.1 配置文件整体结构

Tempo 使用 YAML 格式的配置文件，典型结构如下：

# tempo.yaml 核心结构
server:
  http_listen_port: 3200
  grpc_listen_port: 9095

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

ingester:
  lifecycler:
    ring:
      kvstore:
        store: memberlist
    join_after: 30s
  max_block_duration: 30m
  max_block_bytes: 500_000_000

querier:
  frontend_worker:
    frontend_address: 127.0.0.1:9095
  max_concurrent_queries: 20

compactor:
  compaction:
    block_retention: 48h
    compacted_block_retention: 1h

storage:
  trace:
    backend: s3
    s3:
      bucket: tempo-traces
      endpoint: s3.amazonaws.com
    pool:
      max_workers: 100
      queue_depth: 20000

4.2 核心组件配置详解

下表总结了五个核心组件的职责与关键配置项：

4.3 组件协作流程（SVG 架构图）

下图展示了 Trace 数据从接收到存储的完整流转路径，以及各组件在链路中的位置：

4.4 关键参数调优

4.4.1 max_bytes_per_trace：单 Trace 大小上限

该参数控制单个 Trace 允许的最大字节数，默认值为 5MB。超过此大小的 Trace 会被截断或拒绝，直接影响数据完整性和内存使用。

• 调优场景：高并发微服务调用链极长（如 100+ 服务），单个 Trace 可能超过 10MB。
• 调大影响：Ingester 内存压力增大，查询延迟上升，存储成本增加。
• 调小影响：长 Trace 被截断，丢失关键调用关系，排查问题困难。

4.4.2 ingestion_rate_limit：数据摄入限流

该参数属于 distributor 配置块，用于限制每个 Distributor 实例每秒接收的 Span 数量或字节数，防止突发流量打垮后端。

distributor:
  # 基于 Span 数量的限流
  ingestion_rate_limit: 15000   # 每秒最多 15000 个 Span
  ingestion_burst_size: 30000   # 允许突发 30000 个 Span

  # 基于字节数的限流（二选一）
  ingestion_rate_limit_bytes: 10_000_000   # 每秒最多 10MB
  ingestion_burst_size_bytes: 20_000_000   # 允许突发 20MB

4.5 其他关键参数速查

以下参数在性能调优中同样重要，建议根据实际负载调整：

• ingester.max_block_duration（默认 30m）：Block 在内存中的最大驻留时间。调小可加速数据落盘，但会增加小文件数量。
• ingester.max_block_bytes（默认 500MB）：单个 Block 的最大字节数。调大减少 Compactor 压力，但增加 Ingester 内存风险。
• querier.max_concurrent_queries（默认 20）：Querier 并发查询数。调大提升查询吞吐，但需注意后端存储 IO 能力。
• compactor.compaction.block_retention（默认 48h）：数据保留时间。根据合规要求和存储成本权衡。
• storage.trace.pool.max_workers（默认 100）：存储后端连接池大小。高 IO 场景可调至 200-500。

4.6 配置调优决策树（SVG 流程图）

当遇到性能瓶颈时，可参考以下决策树快速定位需要调整的配置项：

4.7 实战调优案例

排查步骤：

1. 查看 Distributor 监控面板，发现每秒 Span 数峰值达到 22000，超过默认限流值 10000。
2. 将 ingestion_rate_limit 从 10000 提升至 25000，ingestion_burst_size 提升至 50000。
3. 同时检查 Ingester 内存使用，发现 max_block_bytes 为 500MB，内存水位在 70% 左右，暂不调整。
4. 观察 30 分钟后，限流错误消失，数据完整率恢复至 99.9%。

调优总结：