企业官网建设流程全解析

Grafana Tempo 与 AI：用 MCP 服务器和 LLM 优化 API 构建智能 Trace 查询 Agent

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

Grafana Tempo 原生暴露了一套面向 AI Agent 的接入能力：基于 Model Context Protocol（MCP）的/api/mcp服务器、支持Accept: application/vnd.grafana.llm头部的 LLM 优化 API 响应，以及配套的gcx、assistant-cli等 Grafana 家族工具。本文以仓库内官方文档 tempo-and-ai.md 为骨架，结合 mcp.go、llm_marshaler.go 等源码实现，系统讲解如何让 AI Agent 直接检索 Trace、对比链路、计算指标并发现属性，以及在开放 trace 数据给 Agent 之前如何做好权限控制与数据清洗。

Tempo 为 AI 提供什么

Tempo 面向 AI 的接入点可以概括为三条主线：

• MCP 服务器：运行在/api/mcp，让 Agent 用 TraceQL 搜索 trace、按 ID 获取或对比 trace、从 span 数据计算指标、发现可用属性，并把 TraceQL 语法文档作为 MCP Resource 提供给 Agent 按需查阅。
• LLM 优化的 API 响应：trace by ID v2 与 tag values v2 端点接受Accept: application/vnd.grafana.llm请求头，返回精简 JSON，压缩无关细节、降低 token 消耗，让 Agent 在上下文窗口内处理更大规模的 trace。
• Grafana 生态工具：gcx管理 Grafana 资源（看板、数据源、告警规则等），assistant-cli通过 Agent-to-Agent（A2A）协议连接 Grafana Assistant，让 Agent 从 Tempo 的 trace 出发，横向串联日志、指标等其他可观测性信号。

下文分别深入这三个层面，并给出源码级佐证与实战配置。

Model Context Protocol 服务器：让 Agent 直接查询链路数据

端点与传输方式

MCP 服务器挂在/api/mcp，采用streamable-http传输，与 Tempo 其他 API 端点共享同一套鉴权与多租户机制（multitenancy）。也就是说，之前为 Tempo API 配置的认证中间件（如基于租户头部的认证）会原样作用于 MCP 端点。

从源码看，MCP 服务器在 modules/frontend/frontend.go 中按配置开关初始化：

if cfg.MCPServer.Enabled { mcpServer := NewMCPServer(f, apiPrefix, logger, authMiddleware, cfg.MaxQueryExpressionSizeBytes) f.MCPHandler = mcpServer } else { f.MCPHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { http.NotFound(w, r) }) }

对应的配置项定义在 modules/frontend/config.go：

type MCPServerConfig struct { Enabled bool `yaml:"enabled"` }

在 Tempo 配置文件中启用方式如下：

frontend: mcp_server: enabled: true

默认关闭（false），必须显式开启后/api/mcp才可用。MCP 服务器底层基于github.com/mark3labs/mcp-go构建（见 mcp.go），初始化时声明了tempo0.1.0 的服务信息，并注册只读工具与文档资源。

MCP 提供的工具清单

setupTools()（mcp.go）注册了以下 10 个只读工具，全部带有readOnlyHint与destructiveHint=false标注，确保 Agent 无法通过 MCP 修改数据：

以get-attribute-values为例，源码中的工具描述明确给出用途：

Get a list of values for a fully scoped attribute name. This is useful for finding the values of a specific attribute. i.e. you can find all the services in the data by asking for resource.service.name

trace-diff的描述则强调其输出约束：返回紧凑摘要，仅在 patch 不超过 64 KiB 时附带完整 span 级差异；若需要完整细节可显式请求trace-patch-v0，但该格式不保证输出大小上限。Agent 工作流中建议优先使用composed摘要格式以控制 token 开销。

按需获取的文档资源

除了工具，MCP 服务器还注册了 6 个文档资源（setupResources()，mcp.go），URI 形如docs://traceql/basic、docs://traceql/metrics、docs://config/overview等，MIME 类型为text/markdown：

• TraceQL 基础、聚合（aggregates）、结构查询（structural）、指标（metrics）四类语法文档；
• Tempo 配置概览与完整配置参考两类运维文档。

这样 Agent 可以在运行时通过资源读取（或通过docs-traceql/docs-config工具）拉取最新语法，而不是依赖可能过时的训练数据。源码注释还说明了一个实现细节：工具与资源同时注册，是因为“Claude Code 等客户端从不主动请求资源，但会很乐意请求文档工具返回内容”（见 mcp.go 附近注释）。

启用与安全警告

官方文档给出了一条重要安全提醒：MCP 服务器会把 trace 数据返回给调用它的 Agent，而 Agent 可能将数据转发给 LLM 提供商。因此，在把 Agent 接入该端点之前，务必评估 trace 数据内容与组织的数据合规策略。

本地体验可参考 MCP server quick start 章节（见文档 tempo-and-ai.md 中 “To try it locally” 指引），其核心步骤即：开启frontend.mcp_server.enabled: true、启动 Tempo 后让 MCP 客户端（如 Claude Code）连接/api/mcp即可。

LLM 优化的 API 响应：为 Agent 上下文窗口减负

请求头与适用端点

trace by ID v2 和 tag values v2 两个端点支持在请求中携带：

Accept: application/vnd.grafana.llm

携带该头部后，端点返回经过精简的 JSON 格式，剔除无关细节、压缩响应体积，从而降低 token 消耗，让 Agent 在有限的上下文窗口内处理更大的 trace。

精简格式的源码实现

该能力的核心实现在 modules/frontend/combiner/llm_marshaler.go 与 modules/frontend/combiner/common.go。llmMarshaler目前支持两类响应：

switch v := t.(type) { case *tempopb.TraceByIDResponse: return traceByIDResponseToSimplifiedJSON(v) case *tempopb.SearchTagValuesV2Response: return searchTagValuesV2ResponseToSimplifiedJSON(v) }

未支持的类型（如*tempopb.Trace、*tempopb.QueryRangeResponse）会返回util.ErrUnsupported，说明该格式目前仅覆盖上述两个端点。

traceByIDResponseToSimplifiedJSON把原始 OTLP 结构的 trace 重排为trace → services → scopes → spans的层级 JSON，并做如下压缩（见 llm_marshaler.go）：

• 从首个 span 提取traceId；
• 按ResourceSpans聚合服务，service.name提升为serviceName，其余资源属性扁平化为resourcemap；
• 每个 span 精简为spanId、name、parentSpanId、kind、startTimeUnixNano/endTimeUnixNano、计算好的durationMs、扁平化attributes、events、links与status；
• 属性值统一通过extractAnyValue从AnyValue包装中解出原生 Go 类型（字符串、布尔、整数、浮点、字节的 hex 编码、数组、嵌套 KV list，见 llm_marshaler.go）；
• 空字段用omitempty省略，未设置的 span 状态输出默认值STATUS_CODE_UNSET；
• 仅在存在有效统计时附带metrics（inspectedBytes、backendReads、backendBytes等）。

searchTagValuesV2ResponseToSimplifiedJSON则将 tag values 按类型分组为{"tagValues": {type: [values...]}}，同样仅在有数据时附带 metrics（见 llm_marshaler.go）。

使用边界：实验性格式

官方文档明确标注 caution：该精简 LLM 格式处于变动之中，不应作为程序化依赖。建议的使用策略是：

• 交互式或实验性的 Agent 使用：携带Accept: application/vnd.grafana.llm获取精简 JSON；
• 稳定集成：使用 MCP 服务器，或请求标准 JSON / protobuf 格式。

Tempo 中与 AI 工作流强相关的特性

以下特性并非 AI 专有，但它们直接决定了 Agent 能从 trace 数据中获得什么、以及能多快地获得。

TraceQL metrics 正式可用（GA）

MCP 服务器的traceql-metrics-instant与traceql-metrics-range两个工具让 Agent 直接从 trace 数据计算 rate、error、duration（RED）指标。由于 TraceQL metrics 在 Tempo 3.0 已从 experimental 转为正式可用（GA），这些工具查询的是生产就绪的指标引擎。相关实现可进一步参考 pkg/traceql 下的engine_metrics_*系列文件（如 engine_metrics.go、engine_metrics_average.go）。

标签自动补全支持 OR 条件

search tags v2 与 search tag values v2 API 支持 OR 条件，一次请求即可匹配多个取值，避免 Agent 多次往返。当 Agent 通过 MCP 工具探索可查询属性时，更少的往返意味着更快、更廉价的属性发现。

控制 Agent 能访问什么

在向 Agent 开放 trace 数据之前，需要先做好数据治理。若 trace 中包含个人身份信息（PII）或安全令牌，应先用 Tempo CLI 从对象存储中移除相关 trace：

• Redact traces：从对象存储中删除包含敏感数据的 trace；
• Drop traces by ID：直接从 CLI 按 ID 删除特定 trace。

这两项能力在仓库中分别对应 modules/backendscheduler/redaction_window.go 与 modules/backendscheduler/redaction_query.go 等实现，以及 cmd/tempo-cli/cmd-redact.go 命令行入口。清理之后再启用 MCP 或 LLM API，可显著降低敏感数据外泄风险。

Grafana 生态：把 AI Agent 的能力延伸到整个可观测性平台

以下能力并非 Tempo 独有，而是归属于 Grafana 产品家族，对 AI 的价值在于可组合性：一个从 Tempo trace 数据起步的 Agent，可以横向作用于 Grafana 资源、串联其他信号（日志、指标）的调查，并查阅最新文档。

gcx：管理 Grafana 资源的 CLI

gcx是用于管理 Grafana 资源的命令行工具，覆盖看板（dashboards）、数据源（data sources）、告警规则（alerting rules），以及 Grafana Cloud 的 Synthetic Monitoring、SLO、Adaptive Telemetry 等产品。它兼容 Grafana Cloud、Grafana Enterprise 与 Grafana OSS（v12 及以上）。

典型用法：Agent 配合 Tempo MCP 服务器，先定位 trace 中的延迟问题，再通过gcx在终端内查询相关 Prometheus 指标或检查告警规则，无需离开终端即可从“发现”跨到“行动”。

Grafana Assistant CLI

Grafana Assistant 是内置于 Grafana Cloud 的 LLM 驱动工具，支持用自然语言查询数据、构建看板、理解错误，前提是运行在启用了 Grafana Assistant 的实例（例如 Grafana Cloud stack）上。

assistant-cli通过 Agent-to-Agent（A2A）API 将外部 Agent 连接到 Grafana Assistant，从而让 Agent 在终端中串联跨信号调查。示例工作流：Agent 先在 Tempo 中发现失败的 trace，再用assistant-cli把失败与错误日志关联起来，或查询相关指标。

文档以 Markdown 形式提供

Grafana 官方文档以 Markdown 形式随产品发布，Agent 可以拉取最新的参考材料，而不是依赖可能过时的训练数据。Tempo 仓库内的 docs/sources 目录即存放着这些 Markdown 源文档，本文引用的 tempo-and-ai.md 就是其中之一。

落地建议与下一步

将 Tempo 接入 AI Agent 的推荐落地路径：

1. 评估数据：确认 trace 中是否含 PII / 令牌；如有，先用 Tempo CLI 的 redact 或 drop-by-ID 清理对象存储中的敏感 trace。
2. 开启 MCP：在配置中设置frontend.mcp_server.enabled: true，重启后让 Agent 连接/api/mcp。
3. 选择响应格式：交互式探索用Accept: application/vnd.grafana.llm精简 JSON；稳定集成用 MCP 服务器或标准 JSON/protobuf。
4. 延伸生态：安装gcx管理 Grafana 资源，安装assistant-cli连接 Grafana Assistant，让 Agent 在 trace 之外继续调查日志与指标。

官方文档（tempo-and-ai.md）给出的下一步建议与此一致：配置 MCP 服务器让 Agent 访问 trace 数据、安装gcx在终端或 Agent 工作流中管理 Grafana 资源、安装assistant-cli连接 Grafana Assistant。更全面的 AI 能力说明可继续查阅仓库 docs 下的 introduction 系列文档。

参考文件索引

• 官方文档： docs/sources/tempo/introduction/tempo-and-ai.md
• MCP 服务器实现： modules/frontend/mcp.go、modules/frontend/mcp_tools.go、modules/frontend/mcp_tools_test.go
• MCP 开关配置： modules/frontend/config.go、modules/frontend/frontend.go
• LLM 精简格式实现： modules/frontend/combiner/llm_marshaler.go、modules/frontend/combiner/common.go
• TraceQL metrics 引擎： pkg/traceql/engine_metrics.go 及 pkg/traceql 目录下engine_metrics_*文件
• 敏感数据清理： cmd/tempo-cli/cmd-redact.go、modules/backendscheduler/redaction_window.go、modules/backendscheduler/redaction_query.go

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