Grafana Tempo Linux 单节点部署实战：单二进制模式安装、配置与验证

Grafana Tempo Linux 单节点部署实战：单二进制模式安装、配置与验证

【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo

本文以 Grafana Tempo 官方 Linux 部署指南为主线，结合当前仓库源码，完整讲解如何在单台 Linux 主机上以单二进制（monolithic）模式部署一个 Grafana Tempo 实例：从系统资源评估、本地存储准备、deb 包安装，到tempo.yaml逐项配置、systemd 服务管理，以及用telemetrygen和 HTTP API 完成端到端验证。读完本文，你将拥有一套可运行、可排查、可继续扩展的 Tempo 本地测试环境，并理解单二进制模式在源码层面是如何工作的。

部署模式与本文适用范围

Grafana Tempo 支持两种部署模式（详见仓库文档 Deployment modes）：

• Monolithic 模式（单二进制模式）：所有必需组件编译进同一个二进制文件，以tempo -target=all启动（all是默认 target）。不需要 Kafka，distributor 将 trace 数据进程内直接推送给 live-store 与 metrics-generator，再刷写到配置的存储后端，中间没有消息队列。
• Microservices 模式（微服务模式）：每个组件作为独立进程运行，各自指定-target，需要 Kafka 作为写路径的通信载体，是生产环境推荐模式。

从源码看，单二进制模式的判定逻辑集中在 cmd/tempo/app/modules.go 的IsSingleBinary函数。以all为 target 时，Tempo 会做一系列自动化的进程内配置，例如：

• t.cfg.Distributor.PushSpansToKafka = !singleBinary：单二进制模式下 distributor 不走 Kafka，直接进程内推送；
• t.cfg.LiveStore.ConsumeFromKafka = !IsSingleBinary(t.cfg.Target)：live-store 同样不从 Kafka 消费；
• 在 cmd/tempo/main.go 的loadConfig中，单二进制模式会把 generator、live-store 等组件的 ring KVStore 强制设为inmemory，并把实例地址固定为127.0.0.1。

也就是说，单二进制模式牺牲了独立扩缩容能力，换来的是"一条命令跑起完整链路"的极简运维。它适合本地开发、评估验证和低到中等 trace 量的场景。本文所有systemctl操作仅适用于这种单二进制模式，微服务模式下各组件的独立部署不在本文范围内。

如果你正从 Tempo 2.x 升级，请参考仓库中 set-up-for-tracing/setup-tempo 目录下的升级文档，而不是本文的安装步骤。

开始之前：前置条件与系统要求

前置条件

• 一台可访问的 Linux 系统，并拥有部署服务所需的网络与文件系统权限（以root运行，或通过sudo获得相应权限）；
• 可选但强烈建议：已安装 OpenTelemetrytelemetrygen命令行工具，用于向 Tempo 发送测试 trace（它是 OpenTelemetry Collector Contrib 仓库中的独立命令行工具）；
• 可选：一个正在运行的 Grafana 实例，用于可视化地浏览 trace。

系统资源要求

官方给出的以下数值是单节点 monolithic 部署的起步建议，既不是所有环境下的硬性最低要求，也不是生产环境的容量规划建议：

• Tempo 宿主机：4 个 CPU、4–8 GB 内存起步。

如果满足以下任一条件，建议将内存提升到16 GB 或以上：

• 同一台机器上还运行了其他本地组件（如 Grafana、对象存储、Prometheus）；
• 启用了 metrics-generator；
• 测试中等到较高写入速率；
• 增大了 live-trace 缓冲或运行更重的查询负载；
• 希望为基准测试或故障排查预留余量。

将 Tempo 与 Grafana、Prometheus 等服务共置一台机器用于评估没有问题，但会显著增加内存压力；如果内存紧张，请让 Tempo 独占一台主机。生产环境的容量规划取决于你的实际工作负载与基础设施（写入速率、租户数量、查询并发、保留周期、metrics-generator 设置、对象存储性能等），务必用自有负载先行验证再上线。

第一步：准备本地存储

本指南使用本地文件系统作为存储后端。配置中把写前日志（WAL）放在/data/tempo/wal，trace 块放在/data/tempo/blocks；Tempo 在运行期还会使用/var/tempo存放 live store 与内部缓存。

1. 创建数据目录：

   sudo mkdir -p /data/tempo /var/tempo

2. 将目录属主设置为tempo用户（由 deb 包创建）：

   sudo chown -R tempo /data/tempo /var/tempo

本地存储的边界：本地存储适合单节点评估与开发。生产环境请改用对象存储后端（如 AWS S3、Azure Blob Storage、Google Cloud Storage，配置方法见仓库 docs/sources/tempo/configuration 目录下的 hosted-storage 文档）。如果只是想在本地测试中使用 S3 兼容对象存储，也可以参考同一文档中关于 MinIO、SeaweedFS 或rclone搭建本地 S3 兼容存储的介绍。

第二步：下载并安装 Tempo

Tempo 为AMD64（amd64）和64 位 ARM（arm64）两种架构发布 release 二进制；不发布 32 位 ARM（arm）二进制，如需在 32 位 ARM 硬件上运行，只能从源码自行构建。下载前请务必从 releases 页面确认与你操作系统/架构匹配的安装包，并将<TEMPO_VERSION_NUMBER>替换为要安装的版本号（例如3.0.0）。

以下示例适用于支持 deb 包的 Linux 发行版，下载 AMD64（x86_64）架构的二进制：

curl -Lo tempo_<TEMPO_VERSION_NUMBER>_linux_amd64.deb \ https://github.com/grafana/tempo/releases/download/v<TEMPO_VERSION_NUMBER>/tempo_<TEMPO_VERSION_NUMBER>_linux_amd64.deb

安装软件包：

sudo dpkg -i tempo_<TEMPO_VERSION_NUMBER>_linux_amd64.deb

可选：将下载结果与 releases 页面发布的SHA256SUMS文件比对，校验文件完整性。

deb 包安装完成后会创建tempo用户，并注册 systemd 服务。仓库中打包用 systemd 单元文件位于 tools/packaging/tempo.service，其核心内容如下，可以帮助你理解服务的默认启动方式：

[Service] Type=simple User=tempo ExecStart=/usr/bin/tempo -config.file /etc/tempo/config.yml TimeoutSec = 120 Restart = on-failure RestartSec = 2

可以看到：服务以tempo用户运行，启动命令是/usr/bin/tempo -config.file /etc/tempo/config.yml，默认从/etc/tempo/config.yml读取配置，失败后 2 秒自动重启。这与你后面systemctl restart tempo.service的操作是对应的。

第三步：编写 tempo.yaml 配置文件

下面的配置让 Tempo 同时监听OTLP gRPC 与 OTLP HTTP协议。需要注意：OpenTelemetry Collector receiver 默认只绑定localhost，而本示例绑定了所有接口（0.0.0.0）——如果你的 Tempo 实例暴露在公网，这可能带来安全风险。

排错提示：Tempo 的配置解析器对 YAML 缩进非常严格，尤其是storage.trace.wal.path这类嵌套块。如果 Tempo 启动失败，请先检查缩进。

1. 将以下 YAML 保存为tempo.yaml：

   stream_over_http_enabled: true server: http_listen_port: 3200 distributor: receivers: otlp: protocols: grpc: endpoint: "0.0.0.0:4317" http: endpoint: "0.0.0.0:4318" storage: trace: backend: local wal: path: /data/tempo/wal local: path: /data/tempo/blocks usage_report: reporting_enabled: false

2. 将配置复制到 Tempo 配置目录：

   sudo cp tempo.yaml /etc/tempo/config.yml

配置逐项解析

配置块	作用与说明
stream_over_http_enabled: true	允许通过 HTTP 流式返回查询结果，对 trace 搜索与查询体验有直接影响
server.http_listen_port: 3200	Tempo 自身 HTTP API 监听端口。稍后用curl http://localhost:3200/api/search验证时用的就是它
distributor.receivers.otlp.protocols.grpc.endpoint: "0.0.0.0:4317"	OTLP gRPC 接收端点，telemetrygen默认通过它发送 trace
distributor.receivers.otlp.protocols.http.endpoint: "0.0.0.0:4318"	OTLP HTTP 接收端点，供 HTTP 方式的 span 推送使用
storage.trace.backend: local	存储后端类型，本指南为本地文件系统
storage.trace.wal.path: /data/tempo/wal	WAL（写前日志）目录，与第一步创建的目录对应
storage.trace.local.path: /data/tempo/blocks	本地块存储目录
usage_report.reporting_enabled: false	关闭匿名用量上报，本地评估环境通常关闭

仓库中example/docker-compose/single-binary/tempo.yaml提供了同一模式的完整单二进制示例配置，可以对照学习——它额外展示了metrics_generator（含 remote_write 到 Prometheus）、query_frontend.mcp_server等可选配置块。

配置注意事项：不要照抄微服务配置块

这份配置是monolithic 模式（-target=all），所有组件运行在一个进程内，不需要 Kafka。因此ingest、block_builder、live_store_client、backend_scheduler_client等配置块不适用于单二进制模式，不要从微服务示例中照搬。各组件的部署模式归属可对照 Deployment modes 文档中的 "Components by deployment mode" 表格。

第四步：按需扩展基础配置

以下选项是这套基础配置上最常见的扩展，可按需添加。

Block retention（块保留周期）

使用本地存储时，trace 块会在磁盘上持续累积，直到超过配置的保留周期。默认保留14 天（336h）。如果磁盘空间有限，可以在compaction配置块中用block_retention设置更短的保留周期。

源码层面，该字段定义在 tempodb/config.go 的CompactorConfig结构体中：

type CompactorConfig struct { MaxCompactionRange time.Duration `yaml:"compaction_window"` MaxCompactionObjects int `yaml:"max_compaction_objects"` MaxBlockBytes uint64 `yaml:"max_block_bytes"` BlockRetention time.Duration `yaml:"block_retention"` CompactedBlockRetention time.Duration `yaml:"compacted_block_retention"` ... }

即对应 YAML 写法为：

compaction: block_retention: 168h # 例如改为 7 天

Metrics-generator

metrics-generator 从传入的 trace span 中生成RED 指标（rate 速率、errors 错误、duration 耗时）和服务图谱（service graphs）。启用它需要一个 Prometheus 兼容的 remote write 目标，并在overrides块中启用对应 processor。完整配置方式见 metrics-generator 配置文档 与仓库 metrics-from-traces 目录下的说明。可参考example/docker-compose/single-binary/tempo.yaml中的写法：

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

Ingestion limits（写入限制）

Tempo 内置了默认的写入限制，不一定适配所有工作负载。如果日志中出现RATE_LIMITED、TRACE_TOO_LARGE或LIVE_TRACES_EXCEEDED错误，可以在overrides配置中全局或按租户调整这些限制。仓库 modules/overrides 目录下的overrides.go与相关测试即对应这套限制的默认值与校验逻辑。

Backend worker

本配置有意省略了backend_worker.backend_scheduler_addr。在单二进制模式下，Tempo 会自动把 backend worker 配置为连接进程内 scheduler 的原生 gRPC 端口（默认9095）。如果显式把它设置成 HTTP 端口，会产生大量无意义的轮询日志。

这一点在源码中有直接印证：见 cmd/tempo/app/modules.go 的initBackendWorker：

if IsSingleBinary(t.cfg.Target) && t.cfg.BackendWorker.BackendSchedulerAddr == "" { t.cfg.BackendWorker.BackendSchedulerAddr = fmt.Sprintf("127.0.0.1:%d", t.cfg.Server.GRPCListenPort) level.Warn(log.Logger).Log("msg", "Scheduler address is empty in single binary mode. Attempting automatic worker configuration.", "address", t.cfg.BackendWorker.BackendSchedulerAddr) }

即：单二进制模式下若未显式配置地址，Tempo 会用127.0.0.1:<gRPC 端口>（默认 9095）自动接管。

第五步：启动并验证 Tempo 服务

以下systemctl指令仅适用于单二进制模式；将各组件作为独立 systemd 服务运行（微服务模式）不在本文范围内。

1. 重启服务（根据你的安装方式，命令可能略有不同）：

   sudo systemctl restart tempo.service

   也可以把restart替换为stop停止服务，或服务停止后用start再次启动。

2. 确认 Tempo 正在运行：

   systemctl is-active tempo

   应返回active。如果不是，先检查配置文件是否正确，然后重启服务；还可以用journalctl -u tempo查看 Tempo 日志，定位启动失败的明显原因。

3. 确认 Tempo 已创建存储子目录：

   ls /data/tempo/

   应看到wal和blocks两个目录。发送 trace 后，live store 将数据刷写到磁盘，blocks中才会出现 trace 数据——这个过程通常需要15–30 秒。

关于配置校验，仓库入口 cmd/tempo/main.go 还提供了两个实用的启动参数：

• -config.file <path>：指定配置文件路径（systemd 单元默认使用/etc/tempo/config.yml）；
• -config.verify：解析并校验配置后直接退出，适合在重启服务前做配置语法检查：

  sudo -u tempo /usr/bin/tempo -config.file /etc/tempo/config.yml -config.verify

第六步：端到端验证测试链路

详细验证步骤见仓库文档 Validate your local Tempo deployment，核心流程如下（无需额外服务，纯命令行即可完成）：

1. 使用telemetrygen发送测试 trace——以下命令通过 OTLP gRPC 发送 100 条 trace（每秒 20 条、持续 5 秒）：

   telemetrygen traces --otlp-insecure --rate 20 --duration 5s --otlp-endpoint localhost:4317

2. 通过 Tempo HTTP API 搜索近期 trace：

   curl -s http://localhost:3200/api/search | jq .

   应看到一个traces数组，包含你的测试 trace，每条含traceID、rootServiceName、rootTraceName等字段，例如：

   { "traces": [ { "traceID": "abc123...", "rootServiceName": "telemetrygen", "rootTraceName": "lets-go", "startTimeUnixNano": "1776912138880042305" } ] }

   注意：trace 数据要等 live store 将完成的块刷写到磁盘后才会出现在搜索结果中（15–30 秒）。如果traces数组为空，稍等后重试。

3. 用上一步得到的traceID按 ID 拉取完整 trace：

   curl -s http://localhost:3200/api/v2/traces/<TRACE_ID> | jq .

   把<TRACE_ID>替换为真实 trace ID。如果两个命令都能返回 trace 数据，说明你的 Tempo 实例已经正确完成 trace 的摄取、存储与查询。

4. （可选）如果你运行了 Grafana，可以在Connections > Data sources中添加 Tempo 数据源，URL 填http://localhost:3200，保存并测试应显示Data source is working；随后在Explore页面选择 Tempo 数据源并运行Search查询，即可可视化浏览来自telemetrygen的 trace 及其 span。

生产化建议与下一步

再次强调：本流程提供的是适合本地开发与评估的测试安装。若要以它为生产部署起点，请对照所在组织的安全、存储、保留与可用性最佳实践重新审视配置。

验证通过后，可以继续深入以下主题：

• 应用埋点：参考仓库 set-up-for-tracing/instrument-send 目录，为自己应用接入分布式追踪，用真实业务流量替换测试生成器；
• 配置定制：完整配置项说明见仓库 docs/sources/tempo/configuration 目录；
• 监控告警：参考 operations/monitor 目录下的文档，为 Tempo 实例配置 dashboard 与告警规则（仓库 operations/tempo-mixin 目录下还提供了完整的监控 mixin 与预编译 dashboard）；
• 生产扩容：当 trace 量上升、需要独立扩缩容与高可用时，参考 Deployment modes 规划迁移到微服务模式，并引入 Kafka 与对象存储。

【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo