企业官网建设流程全解析

Grafana Tempo 快速上手指南：用 Docker Compose 一键搭建分布式链路追踪环境

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

本篇技术指南围绕 Grafana Tempo 的官方快速开始示例（single-binarydocker-compose 示例）展开，讲解如何用一条docker compose up命令同时拉起 Tempo、Alloy 采集管线、k6-tracing 模拟流量、Prometheus 与 Grafana，并在几分钟内通过 Grafana Explore 与 Traces Drilldown 插件完成链路查询、服务图查看和慢链路根因定位。读完本文，你将掌握 Tempo 单二进制部署的最小可运行方案、各容器职责、核心配置项含义，以及完整的停止、清理与扩展学习路径。

前置条件

要跟随本指南完成操作，需要准备以下环境：

• Git
• Docker（Docker Compose 安装说明）
• Docker Compose 插件（Docker Desktop 已内置）

所有示例都基于 Docker Compose 编排，无需提前安装任何 Go 工具链或单独下载二进制，环境准备非常简单。Tempo 官方提供的 docker-compose 示例集合 中，每一个示例都带有一个docker-compose.yaml清单文件，其中包含了探索链路数据所需的全部选项，包括资源（服务）配置与链路数据生成（模拟写入）配置。这些示例随附的 Tempo 版本与存储配置适合测试或开发场景，直接可用。

提示：如果你不想在本地安装任何依赖，还可以使用 Grafana Labs 的交互式学习环境（Killercoda "Quick start for Tempo"）在线体验，环境中所有依赖均已预先配置完毕。

克隆仓库并启动 Docker

本快速开始使用的是single-binary（单二进制）示例，它用最简单的形态展示了 Tempo 的核心能力。如果你想探索更多运行模式与配置，可以参考 example/docker-compose 目录下的完整示例集合。

1. 克隆 Tempo 仓库：

   git clone https://github.com/grafana/tempo.git

2. 进入示例目录：

   cd tempo/example/docker-compose/single-binary

3. 启动 docker-compose 文件中定义的所有服务：

   docker compose up -d

4. 验证服务是否正常运行：

   docker compose ps

   正常启动后你会看到类似下面的输出，共包含 6 个服务：

   docker compose ps NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS single-binary-alloy-1 docker.io/grafana/alloy@sha256:4f6ddc56ffdcf8a6316748fc5162972e20cb301523cac1bb4a31957df733ae9b "run /etc/alloy/conf…" alloy 7 seconds ago Up 6 seconds 0.0.0.0:12345->12345/tcp, 0.0.0.0:4319->4317/tcp single-binary-grafana-1 docker.io/grafana/grafana@sha256:121a7a9ece6dc10b969f1f96eed64b4f07dfac0d0b8abc070f7cb83bbde86f63 "" grafana 7 seconds ago Up 6 seconds 0.0.0.0:3000->3000/tcp single-binary-k6-tracing-1 ghcr.io/grafana/xk6-client-tracing:v0.0.9 "run /example-script…" k6-tracing 7 hours ago Up 6 seconds single-binary-prometheus-1 docker.io/prom/prometheus:latest "--config.file=/etc/…" prometheus 7 seconds ago Up 6 seconds 0.0.0.0:9090->9090/tcp single-binary-tempo-1 docker.io/grafana/tempo:3.0.0 "-target=all -config…" tempo 7 seconds ago Up 6 seconds 0.0.0.0:3200->3200/tcp, 0.0.0.0:4317-4318->4317-4318/tcp single-binary-vulture-1 docker.io/grafana/tempo-vulture:3.0.0 "-prometheus-listen-…" vulture 7 hours ago Up 6 seconds

各服务职责与端口一览

从 docker-compose.yaml 可以看到，这 6 个服务构成了一个完整的"采集 → 写入 → 存储 → 指标 → 可视化"链路：

其中 Tempo 的数据流向为：k6-tracing以 OTLP gRPC 把链路推送给alloy:4317，Alloy 再转发给tempo:4317（OTLP gRPC）与tempo:4318（OTLP HTTP）；Tempo 的 metrics-generator 把派生指标通过 remote write 写入 Prometheus；Grafana 同时对接 Tempo（链路数据）与 Prometheus（服务图/指标）数据源。

在 Grafana 中探索链路数据

作为 docker-compose 清单的一部分，Grafana 已在3000端口对外提供服务。你可以用它探索由 k6-tracing 服务持续生成的链路数据。

1. 打开浏览器访问http://localhost:3000。

2. 登录后进入Explore页面，选择Tempo数据源并切换到Search标签页，点击Run query即可列出 Tempo 中最近写入的链路；选中任意一条即可查看链路瀑布图（trace diagram）。示例中预置了匿名登录（GF_AUTH_ANONYMOUS_ENABLED=true）并禁用了登录表单，因此无需输入账号密码即可进入。

3. Tempo 启动几分钟后，回到 Explore 页面中 Tempo 数据源的Service graph标签页，点击Run query即可查看服务图。这张图由 Tempo 的metrics-generator基于链路数据实时生成——服务图中的每条边都来自service-graphs处理器对 span 间调用关系的聚合。

4. 若要停止所有服务：

   docker compose down -v

   -v参数会一并删除名为tempo-data的命名卷，即清理 Tempo 本地存储的 WAL 与 block 数据，保证下次启动环境干净。

关于 Grafana 数据源配置

grafana-datasources.yaml 中预置了三个数据源：Prometheus（http://prometheus:9090）、Tempo (yes streaming)（默认数据源，启用了 streaming 搜索与流式指标）、Tempo (no streaming)（对照用途）。其中 Tempo 数据源的serviceMap.datasourceUid指向 Prometheus，这正是 Service graph 面板能展示指标数据的基础。

使用 Traces Drilldown 插件定位慢链路

Traces Drilldown 是 Grafana 提供的"无需编写查询"的链路探索方式，适合在不熟悉 TraceQL 的情况下快速发现性能问题。在 Grafana 容器启动参数中，已通过GF_FEATURE_TOGGLES_ENABLE=traceqlEditor metricsSummary开启了相关特性开关。

1. 打开浏览器访问http://localhost:3000/a/grafana-exploretraces-app。

2. 在过滤器栏中，有一个下拉菜单默认设置为Rate（速率）视图下的Full traces（完整链路）。把它改为Duration（耗时）并选择All spans（全部 span）。

切换后，面板会呈现以下视图：

• 顶部的直方图展示 span 耗时的分布。颜色越浅表示落在该耗时区间的 span 越多。在示例中，大多数 span 落在537ms附近，这可以视为该系统的平均耗时水平。
• 直方图中高出平均线的峰值，表示存在耗时远超平均值的 span（示例中最高可达2.15s）。这些极有可能是造成性能问题的 span，可以进一步下钻定位根因。

3. 点击导航栏中的Slow traces标签页，查看系统中耗时最长的链路。示例中shop-backend服务是慢链路的主要来源，这通常发生在用户发起article-to-cart操作时。从该视图可以选中Trace Name打开Trace View面板。

Trace View面板提供链路的详细视图，面板分为三个区域：

• 顶部区域：显示链路 ID、总耗时以及生成该链路的服务。
• 中部区域：显示链路时间线。每个 span 用一条水平条表示，条的颜色代表 span 的状态，条的宽度代表 span 的耗时。
• 底部区域：显示当前选中 span 的详细信息，包括 span 名称、耗时与标签（tags）。

4. 下钻到shop-backend的 span 后可以看到，place-articles操作挂有一个异常（exception）事件，这很可能就是慢链路的根因所在。

如果你想更深入地了解 Traces Drilldown 插件的面板概念，可以参考 Grafana 官方文档中的 "Traces Drilldown Concepts"。

深入解析 single-binary 示例的底层配置

快速上手之外，本示例的配置本身就是一套极佳的 Tempo 学习材料。下面结合仓库源码与配置文件逐项拆解。

Tempo 主配置：tempo.yaml

tempo.yaml 以-target=all模式运行，即单进程承载 Tempo 的全部模块。关键配置如下：

stream_over_http_enabled: true server: http_listen_port: 3200 log_level: info distributor: receivers: otlp: protocols: grpc: endpoint: "tempo:4317" http: endpoint: "tempo:4318" metrics_generator: registry: external_labels: source: tempo cluster: docker-compose storage: path: /var/tempo/generator/wal remote_write: - url: http://prometheus:9090/api/v1/write send_exemplars: true query_frontend: mcp_server: enabled: true storage: trace: backend: local wal: path: /var/tempo/wal local: path: /var/tempo/blocks overrides: defaults: metrics_generator: processors: ["span-metrics", "service-graphs"] generate_native_histograms: both usage_report: reporting_enabled: false

各配置段的作用：

• stream_over_http_enabled：开启通过 HTTP 的流式查询响应，这是 Grafana 端 streaming 搜索/指标能力的前提。
• server：Tempo 查询与内部 API 监听端口为3200，日志级别为info。
• distributor.receivers.otlp：以 OTLP 协议接收链路，同时启用 gRPC（4317）与 HTTP（4318）两个端点；注释中预留的log_received_spans/log_discarded_spans可用于调试写入数据。
• metrics_generator：为派生指标设置外部标签（source=tempo、cluster=docker-compose），指标 WAL 存放在/var/tempo/generator/wal，并通过 remote write 推送到 Prometheus，且send_exemplars: true允许携带 exemplar（示例/样例数据）。
• query_frontend.mcp_server：开启 Tempo 的 MCP（Model Context Protocol）服务器，可让 LLM Agent 直接查询链路数据（详见 mcp.go 相关实现）。
• storage.trace：使用local本地文件系统后端，WAL 存于/var/tempo/wal，最终 block 存于/var/tempo/blocks——这是适合测试与开发的最小存储方案，生产环境建议替换为 S3/GCS/Azure 等对象存储。
• overrides.defaults.metrics_generator：启用了span-metrics（按 span 维度产出 RED 指标）与service-graphs（服务调用关系图）两个处理器，并让 native histograms 同时生成 classic 与 native 两套直方图（both），与 Prometheus 侧的--enable-feature=native-histograms相呼应。
• usage_report：关闭匿名用量上报。

采集管线：config.alloy

config.alloy 定义了 Alloy 的 OTLP 接收与转发管线：otelcol.receiver.otlp在0.0.0.0:4317（gRPC）与0.0.0.0:4318（HTTP）接收数据，随后交给otelcol.exporter.otlp，其上游地址由环境变量ALLOY_OTLP_UPSTREAM（即tempo:4317）指定，并以insecure（明文）方式转发给 Tempo。k6-tracing 之所以把ENDPOINT设为alloy:4317，正是因为采集入口在 Alloy 而非 Tempo 直接对外。

数据完整性校验：tempo-vulture

vulture容器通过 main.go 中定义的一组命令行参数运行：

-prometheus-listen-address=:8080 -tempo-query-url=http://tempo:3200 -tempo-push-url=http://tempo:4317

即：在8080暴露校验指标供 Prometheus 抓取，向tempo:4317推送测试链路，再从tempo:3200查询并校验数据是否完整写回——这是 Tempo 数据完整性的自动化看门狗。Prometheus 的抓取目标（tempo:3200、vulture:8080）在 prometheus.yaml 中定义。

更多 Docker Compose 示例一览

本仓库的 example/docker-compose 目录提供了多种运行模式，可按需选用：

例如 Distributed 示例把 Tempo 拆分为独立微服务，并用 MinIO 模拟 S3 对象存储，更贴近生产拓扑。

可选：构建本地镜像运行

以上示例默认拉取已发布的grafana/tempo:3.0.0官方镜像，这一步通常并非必需。如果你希望在本地代码改动的基础上运行示例，可以从仓库根目录构建镜像，并在示例目录中指定TEMPO_IMAGE_TAG：

# 在仓库根目录执行 make docker-images # 在示例目录执行 TEMPO_IMAGE_TAG=latest docker compose up

下一步学习

至此，你已经成功搭建了 Tempo + Grafana 环境，并探索了 k6-tracing 服务生成的链路数据。接下来可以继续：

• 按照 Set up for tracing 文档正式部署 Tempo（对应仓库中的 modules 与 tempodb 实现）。
• 学习如何为你的应用接入 instrumentation 以产生真实的链路数据。
• 熟悉 TraceQL 查询语言，编写更精确的链路检索与聚合查询；在 Explore 中可先试用{}（查询所有链路）与{} | rate()（所有 span 的速率）这类基础表达式。

备选：完整的 MLTP 多信号示例

如果你想要一个同时包含指标（Metrics）、日志（Logs）、链路（Traces）与分析（Profiling）多种可观测性信号的演示环境，可以尝试intro-to-mltp项目。它提供了一个自包含的学习环境，用于了解 Mimir、Loki、Tempo、Pyroscope 与 Grafana 的协同工作方式，包含每个组件的详细说明和单实例部署的注释配置，其数据也可以推送到 Grafana Cloud。

延伸阅读

• 应用接入与 instrumentation 指南：Set up for tracing 系列文档
• 部署与运维正式环境：参考 Set up for tracing 中的部署章节，以及仓库内 example/helm 与 operations 目录提供的 Helm Chart、Jsonnet 与监控 Mixin 资源。

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