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 modesMonolithic 模式单二进制模式所有必需组件编译进同一个二进制文件以tempo -targetall启动all是默认 target。不需要 Kafkadistributor 将 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/waltrace 块放在/data/tempo/blocksTempo 在运行期还会使用/var/tempo存放 live store 与内部缓存。创建数据目录sudo mkdir -p /data/tempo /var/tempo将目录属主设置为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 兼容存储的介绍。第二步下载并安装 TempoTempo 为AMD64amd64和64 位 ARMarm64两种架构发布 release 二进制不发布 32 位 ARMarm二进制如需在 32 位 ARM 硬件上运行只能从源码自行构建。下载前请务必从 releases 页面确认与你操作系统/架构匹配的安装包并将TEMPO_VERSION_NUMBER替换为要安装的版本号例如3.0.0。以下示例适用于支持 deb 包的 Linux 发行版下载 AMD64x86_64架构的二进制curl -Lo tempo_TEMPO_VERSION_NUMBER_linux_amd64.deb \ https://github.com/grafana/tempo/releases/download/vTEMPO_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] Typesimple Usertempo 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 启动失败请先检查缩进。将以下 YAML 保存为tempo.yamlstream_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将配置复制到 Tempo 配置目录sudo cp tempo.yaml /etc/tempo/config.yml配置逐项解析配置块作用与说明stream_over_http_enabled: true允许通过 HTTP 流式返回查询结果对 trace 搜索与查询体验有直接影响server.http_listen_port: 3200Tempo 自身 HTTP API 监听端口。稍后用curl http://localhost:3200/api/search验证时用的就是它distributor.receivers.otlp.protocols.grpc.endpoint: 0.0.0.0:4317OTLP gRPC 接收端点telemetrygen默认通过它发送 tracedistributor.receivers.otlp.protocols.http.endpoint: 0.0.0.0:4318OTLP HTTP 接收端点供 HTTP 方式的 span 推送使用storage.trace.backend: local存储后端类型本指南为本地文件系统storage.trace.wal.path: /data/tempo/walWAL写前日志目录与第一步创建的目录对应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 模式-targetall所有组件运行在一个进程内不需要 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-generatormetrics-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: trueIngestion 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 的initBackendWorkerif 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 服务运行微服务模式不在本文范围内。重启服务根据你的安装方式命令可能略有不同sudo systemctl restart tempo.service也可以把restart替换为stop停止服务或服务停止后用start再次启动。确认 Tempo 正在运行systemctl is-active tempo应返回active。如果不是先检查配置文件是否正确然后重启服务还可以用journalctl -u tempo查看 Tempo 日志定位启动失败的明显原因。确认 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核心流程如下无需额外服务纯命令行即可完成使用telemetrygen发送测试 trace——以下命令通过 OTLP gRPC 发送 100 条 trace每秒 20 条、持续 5 秒telemetrygen traces --otlp-insecure --rate 20 --duration 5s --otlp-endpoint localhost:4317通过 Tempo HTTP API 搜索近期 tracecurl -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数组为空稍等后重试。用上一步得到的traceID按 ID 拉取完整 tracecurl -s http://localhost:3200/api/v2/traces/TRACE_ID | jq .把TRACE_ID替换为真实 trace ID。如果两个命令都能返回 trace 数据说明你的 Tempo 实例已经正确完成 trace 的摄取、存储与查询。可选如果你运行了 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考