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/tempoGrafana Tempo 原生暴露了一套面向 AI Agent 的接入能力基于 Model Context ProtocolMCP的/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-AgentA2A协议连接 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.gotype 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与destructiveHintfalse标注确保 Agent 无法通过 MCP 修改数据工具名参数说明traceql-searchquery必填、start、end用 TraceQL 查询搜索 trace时间参数为 RFC3339 格式缺省时检索过去 1 小时traceql-metrics-instantquery必填、start、end计算 TraceQL metrics 查询在即时点的单一指标值traceql-metrics-rangequery必填、start、end计算从 start 到 end 的指标序列seriesget-tracetrace_id必填按 trace ID 获取完整 tracetrace-diffbase_trace_id、compare_trace_id均必填以及base_start/base_end、compare_start/compare_end、format对比两条完整 traceformat支持composed默认≤64 KiB 时附带完整 span 级 patch、trace-patch-v0、native等取值get-attribute-namesscope可选列出可用于 TraceQL 的属性名scope可取 span、resource、event、link、instrumentationget-attribute-valuesname必填、filter-query可选获取某个完整限定属性名的取值例如resource.service.name可列出全部服务名filter-query支持单 spanset 且仅连接的条件用于先过滤再取值docs-traceqlname必填按需获取 TraceQL 文档basic、aggregates、structural、metricsdocs-configname必填获取 Tempo 配置文档overview 或 reference以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.nametrace-diff的描述则强调其输出约束返回紧凑摘要仅在 patch 不超过 64 KiB 时附带完整 span 级差异若需要完整细节可显式请求trace-patch-v0但该格式不保证输出大小上限。Agent 工作流中建议优先使用composed摘要格式以控制 token 开销。按需获取的文档资源除了工具MCP 服务器还注册了 6 个文档资源setupResources()mcp.goURI 形如docs://traceql/basic、docs://traceql/metrics、docs://config/overview等MIME 类型为text/markdownTraceQL 基础、聚合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仅在存在有效统计时附带metricsinspectedBytes、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 正式可用GAMCP 服务器的traceql-metrics-instant与traceql-metrics-range两个工具让 Agent 直接从 trace 数据计算 rate、error、durationRED指标。由于 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 从对象存储中移除相关 traceRedact traces从对象存储中删除包含敏感数据的 traceDrop 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 资源的 CLIgcx是用于管理 Grafana 资源的命令行工具覆盖看板dashboards、数据源data sources、告警规则alerting rules以及 Grafana Cloud 的 Synthetic Monitoring、SLO、Adaptive Telemetry 等产品。它兼容 Grafana Cloud、Grafana Enterprise 与 Grafana OSSv12 及以上。典型用法Agent 配合 Tempo MCP 服务器先定位 trace 中的延迟问题再通过gcx在终端内查询相关 Prometheus 指标或检查告警规则无需离开终端即可从“发现”跨到“行动”。Grafana Assistant CLIGrafana Assistant 是内置于 Grafana Cloud 的 LLM 驱动工具支持用自然语言查询数据、构建看板、理解错误前提是运行在启用了 Grafana Assistant 的实例例如 Grafana Cloud stack上。assistant-cli通过 Agent-to-AgentA2AAPI 将外部 Agent 连接到 Grafana Assistant从而让 Agent 在终端中串联跨信号调查。示例工作流Agent 先在 Tempo 中发现失败的 trace再用assistant-cli把失败与错误日志关联起来或查询相关指标。文档以 Markdown 形式提供Grafana 官方文档以 Markdown 形式随产品发布Agent 可以拉取最新的参考材料而不是依赖可能过时的训练数据。Tempo 仓库内的 docs/sources 目录即存放着这些 Markdown 源文档本文引用的 tempo-and-ai.md 就是其中之一。落地建议与下一步将 Tempo 接入 AI Agent 的推荐落地路径评估数据确认 trace 中是否含 PII / 令牌如有先用 Tempo CLI 的 redact 或 drop-by-ID 清理对象存储中的敏感 trace。开启 MCP在配置中设置frontend.mcp_server.enabled: true重启后让 Agent 连接/api/mcp。选择响应格式交互式探索用Accept: application/vnd.grafana.llm精简 JSON稳定集成用 MCP 服务器或标准 JSON/protobuf。延伸生态安装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.mdMCP 服务器实现 modules/frontend/mcp.go、modules/frontend/mcp_tools.go、modules/frontend/mcp_tools_test.goMCP 开关配置 modules/frontend/config.go、modules/frontend/frontend.goLLM 精简格式实现 modules/frontend/combiner/llm_marshaler.go、modules/frontend/combiner/common.goTraceQL 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考