搬瓦工部署 Grafana Tempo 分布式追踪系统教程

Grafana Tempo 是一款高性价比的分布式追踪后端，专注于大规模追踪数据的存储和查询。与 Jaeger 和 Zipkin 不同，Tempo 不需要索引，仅依赖对象存储或本地文件系统，极大地降低了运维成本和资源消耗。Tempo 与 Grafana 深度集成，支持 TraceQL 查询语言，是 Grafana 可观测性栈的重要组成部分。本文将介绍如何在搬瓦工 VPS 上部署 Tempo。部署前请确保已安装 Docker 和 Docker Compose。

一、Tempo 核心优势

无需索引：只存储追踪 ID 到数据块的映射，存储成本极低。
多协议支持：同时接收 Jaeger、Zipkin、OpenTelemetry 和 OpenCensus 格式的数据。
TraceQL：强大的查询语言，支持按 Span 属性搜索追踪数据。
Grafana 集成：在 Grafana 中直接查看追踪瀑布图，关联日志和指标。
低资源消耗：单体模式下资源需求很低，适合中小规模场景。

二、系统要求

操作系统：Ubuntu 20.04+ 或 Debian 11+。
内存：至少 1GB，推荐 2GB。
磁盘：至少 10GB 可用空间。
Docker：已安装 Docker 和 Docker Compose。

搬瓦工 VPS 方案推荐参考全部方案，购买时使用优惠码 NODESEEK2026 可享 6.77% 折扣，购买入口：bwh81.net。

三、创建项目目录

mkdir -p /opt/tempo/{config,data} && cd /opt/tempo

四、编写 Tempo 配置文件

cat > /opt/tempo/config/tempo.yaml <<'EOF'
server:
  http_listen_port: 3200

distributor:
  receivers:
    jaeger:
      protocols:
        thrift_http:
          endpoint: "0.0.0.0:14268"
        grpc:
          endpoint: "0.0.0.0:14250"
    zipkin:
      endpoint: "0.0.0.0:9411"
    otlp:
      protocols:
        grpc:
          endpoint: "0.0.0.0:4317"
        http:
          endpoint: "0.0.0.0:4318"

ingester:
  trace_idle_period: 10s
  max_block_bytes: 1048576
  max_block_duration: 5m

compactor:
  compaction:
    block_retention: 48h

storage:
  trace:
    backend: local
    wal:
      path: /var/tempo/wal
    local:
      path: /var/tempo/blocks

metrics_generator:
  registry:
    external_labels:
      source: tempo
  storage:
    path: /var/tempo/generator/wal
    remote_write:
      - url: http://prometheus:9090/api/v1/write
        send_exemplars: true

overrides:
  defaults:
    metrics_generator:
      processors: [service-graphs, span-metrics]
EOF

五、编写 Docker Compose 配置

cat > /opt/tempo/docker-compose.yml <<'EOF'
version: '3.8'

services:
  tempo:
    image: grafana/tempo:latest
    restart: always
    command: ["-config.file=/etc/tempo/tempo.yaml"]
    ports:
      - "3200:3200"   # HTTP API
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP
      - "9411:9411"   # Zipkin
      - "14268:14268" # Jaeger HTTP
    volumes:
      - ./config/tempo.yaml:/etc/tempo/tempo.yaml:ro
      - tempo_data:/var/tempo

volumes:
  tempo_data:
EOF

六、启动服务

cd /opt/tempo
docker compose up -d

验证服务状态：

curl http://localhost:3200/ready
curl http://localhost:3200/status

七、在 Grafana 中配置 Tempo 数据源

在 Grafana 中添加 Tempo 类型的数据源：

URL：http://tempo:3200
启用 TraceQL 搜索
可选：配置与 Loki 的日志关联和与 Prometheus 的指标关联

八、发送追踪数据

应用程序可以通过以下协议发送追踪数据到 Tempo：

OTLP gRPC：your_server_ip:4317（推荐）
OTLP HTTP：http://your_server_ip:4318/v1/traces
Jaeger HTTP：http://your_server_ip:14268/api/traces
Zipkin：http://your_server_ip:9411/api/v2/spans

九、TraceQL 查询示例

在 Grafana 中使用 TraceQL 搜索追踪数据：

# 查找特定服务的追踪
{ resource.service.name = "my-api" }

# 查找持续时间超过 1 秒的 Span
{ duration > 1s }

# 查找错误状态的 Span
{ status = error }

# 组合条件
{ resource.service.name = "my-api" && span.http.status_code >= 500 }

十、常见问题

追踪数据未出现在 Grafana 中

确认应用程序正确配置了 Trace Exporter 端点，并检查 Tempo 日志是否有接收记录：

docker compose logs tempo | grep "received"

磁盘空间增长

调整 block_retention 参数控制数据保留时间，确保 Compactor 正常工作。

总结

Grafana Tempo 是成本效益最高的分布式追踪后端，特别适合已经在使用 Grafana 的团队。如果你需要更丰富的 UI 和分析功能，可以参考 Jaeger；如果偏好简单的追踪方案，参考 Zipkin。选购搬瓦工 VPS 使用优惠码 NODESEEK2026 可享 6.77% 折扣。