Grafana Tempo MCP Server为 AI 助手与 LLM 开放分布式链路追踪数据【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempoGrafana Tempo 内嵌了一个基于 Model Context ProtocolMCP的服务器让 AI 助手与大语言模型LLM可以直接通过 TraceQL 查询和多种只读端点检索、对比和分析分布式链路追踪数据。本文将围绕 Tempo 官方文档docs/sources/tempo/api_docs/mcp-server.md展开完整讲解该 MCP 服务器的启用配置、9 个内置工具与 7 个文档资源的使用方法、Streamable HTTP 传输接入方式并结合仓库源码modules/frontend/mcp.go、modules/frontend/mcp_tools.go剖析其底层实现帮助读者快速搭建一个可由 Claude Code、Cursor 等 MCP 客户端直接使用的 Tempo AI 查询入口。一、MCP Server 是什么MCPModel Context Protocol是 AI 助手与外部数据源之间的标准化开放协议。Tempo 将 MCP 服务器直接编译进自身二进制运行 Tempo 时即随 query-frontend 模块一起提供服务AI 助手可以通过统一的 MCP 协议调用工具Tools与读取资源Resources从而在对话中实时查询链路数据而无需预先将全部数据塞进模型上下文。在 Tempo 的架构中MCP 服务器由 query-frontend查询前端持有并复用其已有的查询管线它把 MCP 工具调用翻译成 Tempo 内部 HTTP 请求转发给既有的 Search、Metrics、TraceByID、TraceDiff 等 handler并把响应以 LLM 友好的 JSON 格式返回。从源码看该能力集中在 modules/frontend/mcp.go 中NewMCPServer基于mark3labs/mcp-go库创建底层 MCP 服务器服务名为tempo版本0.1.0并注册工具与资源同时声明了readOnly、non-destructive、non-open-world等只读注解见newReadOnlyTool表明所有工具都不会修改或删除数据。每次工具调用还会通过tempo_query_frontend_mcp_calls_total{tool...}指标计数定义于 modules/frontend/mcp_tools.go便于运维观测使用情况。二、启用与配置MCP 服务器默认关闭需要显式开启。官方推荐在 YAML 配置的query_frontend块下启用query_frontend: mcp_server: enabled: true也可以通过命令行 flag 开启--query-frontend.mcp-server.enabledtrue对应到源码MCPServerConfig结构体只有一个enabled字段见 modules/frontend/config.go并在RegisterFlagsAndApplyDefaults中注册了该 flag默认值为false。源码注释明确说明启用 MCP 服务器意味着可能将追踪数据发送给 LLM 或 LLM 提供商因此必须由用户显式开启见 modules/frontend/config.go。警告启用此功能可能导致追踪数据被传递给 LLM 或 LLM 提供商。请结合自身追踪数据的内容与组织政策审慎决定是否开启。从 modules/frontend/frontend.go 可以看到启用后 query-frontend 会创建MCPServer并挂载为MCPHandler未启用时该路径直接返回 404。MCP 服务器与其他 Tempo API 端点共用同一套认证与多租户multi-tenancy机制因此租户隔离与鉴权策略天然适用。官方提供的单二进制 docker-compose 示例example/docker-compose/single-binary/tempo.yaml也默认开启了query_frontend.mcp_server.enabled便于本地快速试验。三、可用工具ToolsMCP 服务器向 AI 助手暴露以下工具全部为只读操作工具说明traceql-search使用 TraceQL 查询检索链路tracestraceql-metrics-instant根据 TraceQL metrics 查询返回单个指标值traceql-metrics-range根据 TraceQL metrics 查询返回指标序列get-trace按 Trace ID 检索指定链路trace-diff对比两条完整链路并返回差异get-attribute-names获取可用于 TraceQL 查询的属性名列表get-attribute-values获取指定作用域属性名的取值docs-traceql检索 TraceQL 文档基础、聚合、结构化、指标docs-config检索 Tempo 配置文档总览、参考这些工具的名称与参数定义集中在 modules/frontend/mcp.go 的setupTools中下面逐个详解。3.1 traceql-search按 TraceQL 查询检索链路参数query必填TraceQL 查询字符串。start/end可选RFC3339 格式的查询时间范围。不传时默认搜索过去 1 小时传入时start必须早于end。在实现中modules/frontend/mcp_tools.go该工具会先解析并校验 TraceQL 查询若查询实际是 metrics 查询包含BatchSpanProcessor或SeriesProcessor会明确提示改用traceql-metrics-instant或traceql-metrics-range随后把查询转换为标准的/api/search请求交给SearchHandler执行。搜索默认时间窗口为now-1h到now。3.2 traceql-metrics-instant 与 3.3 traceql-metrics-rangetraceql-metrics-instant给定 TraceQL metrics 查询返回当前时刻或end时刻的单一指标值。大多数指标类问题用即时值即可回答。traceql-metrics-range给定 TraceQL metrics 查询返回从start到end的指标序列。二者共用query必填、start/end可选默认过去 1 小时参数。实现上分别把查询转为/api/metrics/queryinstant与/api/metrics/queryrange请求见 modules/frontend/mcp_tools.go并做反向校验如果传入的是普通搜索查询而非 metrics 查询会提示改用traceql-search。两者都带destructivefalse注解声明只读语义。3.4 get-trace按 Trace ID 检索完整链路参数trace_id必填要检索的链路 ID。实现中将请求构造为GET /api/v2/traces/{trace_id}并交给TraceByIDHandlerV2处理见 modules/frontend/mcp_tools.go。3.5 trace-diff实验性对比两条完整链路。参数base_trace_id必填基线链路的 Trace ID。compare_trace_id必填对比链路的 Trace ID。format可选输出格式可选值为trace-summary-v0-composed默认、trace-summary-v0-native、trace-patch-v0显式传空字符串视为非法。base_start/base_end可选基线链路的 RFC3339 时间范围二者必须同时提供。compare_start/compare_end可选对比链路的时间范围同样必须成对出现。行为约定默认省略format返回trace-summary-v0-composed始终包含紧凑摘要当 span 级 patch 不超过 64 KiB 时附带完整 patch。64 KiB 限制只针对附带的 patch不影响完整的 composed 响应本身。设formattrace-summary-v0-native只返回紧凑摘要设formattrace-patch-v0返回完整的 span 级 patch。完整 patch 响应不保证输出大小上限。若 composed 响应中包含patchOmitted字段说明 patch 因过大被省略先用摘要做初步分析仅在确实需要 span 级证据、且客户端能接受patchOmitted.bytes大小的 patch 时再请求trace-patch-v0。未指定时间范围时Tempo 会搜索所有 block 来定位该链路部分partial链路会被拒绝因为其对比结果可能不准确。上述约束在 modules/frontend/mcp_tools.go 的handleTraceDiff、traceDiffFormat与parseTraceDiffRange中逐一实现format默认值为trace-summary-v0-composed且在 schema 层做了minLength(1)与枚举校验见 modules/frontend/mcp.go时间范围参数必须成对单独出现会报错。底层对比逻辑位于 pkg/model/tracediff其版本常量VersionTraceSummaryV0Composed、VersionTraceSummaryV0Native、VersionTracePatchV0与工具定义直接对应。功能测试 modules/frontend/mcp_functional_test.go 验证了默认格式、空format报错、POST 到/api/tracediff端点、携带Accept: application/json与 LLM 友好的Accept头等行为。3.6 get-attribute-names获取可用于 TraceQL 查询的属性名列表参数scope可选按作用域过滤属性可取span、resource、event、link、instrumentation不传则返回全部属性。该工具直接调用搜索标签 V2 接口见 modules/frontend/mcp_tools.go。3.7 get-attribute-values获取指定作用域属性名的取值参数name必填要查询取值的属性名例如span.http.method、resource.service.name。filter-query可选应用于属性值的过滤查询。它只能包含一个 spanset且只能用连接的多个条件形如{ cond cond ... }。典型用途是“先按服务过滤再枚举该服务的端点”例如查询span.http.endpoint的取值时用resource.service.name作为过滤条件。实现上modules/frontend/mcp_tools.go会调用traceql.ExtractConditionGroups校验过滤查询再构造GET /api/v2/search/tag/{name}/values请求交给SearchTagsValuesV2Handler。3.8 docs-traceql 与 3.9 docs-config这两个工具以“工具”形式提供文档检索name参数决定返回哪份文档docs-traceqlname取basic、aggregates、structural、metrics之一。docs-configname取overview或reference未知取值会回退到 overview不会报错。之所以既提供 Resources 又提供同名 Tools源码注释给出原因Claude Code 等客户端几乎不会主动请求 Resources但会很好地通过工具调用获取内容见 modules/frontend/mcp.go。所有工具调用结果都会附带元数据标注type如search-results、metrics-instant、trace-diff、encoding与version便于 LLM 识别响应类型。3.10 统一只读语义与查询大小限制所有工具都通过newReadOnlyTool打上readOnlytrue、destructivefalse、openWorldfalse注解。此外涉及查询字符串的工具搜索、指标、属性值过滤会调用validateTraceQLQuerySize校验 TraceQL 表达式大小超过query_frontend.max_query_expression_size_bytes默认 128 KiB见 modules/frontend/config.go的查询会被拒绝。四、可用资源ResourcesMCP 服务器同时提供以下文档资源MCP 客户端可通过标准resources/read读取资源 URI说明docs://traceql/basicTraceQL 基础语法intrinsics、操作符与属性docs://traceql/aggregatesTraceQL 聚合函数count、sum 等docs://traceql/structural高级结构化查询模式docs://traceql/metrics用 TraceQL 从链路数据生成指标docs://config/overview各顶层配置块职责的定位图docs://config/reference全部配置项及其默认值的完整参考docs://traceql/query兼容旧版的 TraceQL 查询文档内容同 basic资源内容以text/markdown提供直接取自仓库内嵌的文档源文件TraceQL 文档对应 modules/frontend/docs/basic.md、aggregates.md、structural.md、metrics.md配置文档对应 config-overview.md 与 config-reference.md。资源注册逻辑见 modules/frontend/mcp.go。docs://config/overview是一份人工维护的“配置定位图”列出target、server、distributor、querier、query_frontend、metrics_generator、storage、overrides、memberlist、cache等顶层配置块各自控制的职责docs://config/reference则是由默认配置生成的完整清单。这样 AI 助手在回答“如何配置 Tempo”类问题时可以先取 overview 定位再取 reference 查具体键名与默认值。功能测试 modules/frontend/mcp_functional_test.go 验证了这些资源可通过 MCP 协议列出与读取。五、快速开始与 Claude Code 集成官方提供了使用 dummy 数据与 Claude Code 快速体验的步骤在仓库根目录运行单二进制 docker-compose 示例MCP 服务器将暴露在http://localhost:3200/api/mcpcd example/docker-compose/single-binary docker compose up该示例的 tempo.yaml 已开启query_frontend.mcp_server.enabled并使用storage.trace.backend: local存储。向 Claude Code 注册 MCP 服务器引用claude mcp add --transporthttp tempo http://localhost:3200/api/mcp启动claude然后直接向它提问即可例如让它搜索特定错误属性的链路、对比两条链路、或解释某段 TraceQL 语法。端到端集成测试integration/api/mcp_test.go使用config-mcp.yaml覆盖配置启动 Tempo通过mcpclient.NewStreamableHttpClient连接http://endpoint:3200/api/mcpapi.PathMCP验证了列出工具、检索链路、执行 trace-diff 等完整流程。六、传输方式与客户端接入Tempo MCP 服务器使用 Streamable HTTP 传输Streamable HTTP transport。任何支持该传输的 MCP 客户端都可以直接用下面的 URL 连接http://tempo-host:port/api/mcp例如在 Cursor 中可以在 MCP 配置里添加服务器并将type设为streamableHttp。如果客户端原生不支持 Streamable HTTP可以使用mcp-remote包作为桥接层接入。从实现看Tempo 基于mcp-go的server.NewStreamableHTTPServer提供服务见 modules/frontend/mcp.goHTTP 路径即/api/mcp在 query-frontend 挂载时该 handler 会套上认证中间件见 modules/frontend/mcp.go因此多租户鉴权与既有 API 完全一致。七、安全与数据合规注意启用 MCP 服务器会把链路数据交给 AI 助手而 AI 助手可能进一步将数据转发给 LLM 提供商因此在开启前需要评估链路数据中可能包含请求路径、用户标识、IP 等敏感信息请按组织数据合规政策决定是否开放MCP 端点与 Tempo 其他 API 共用认证与多租户机制但仍应通过鉴权、网络隔离等手段限制可访问该端点的客户端只读注解readOnly/destructivefalse从工具语义上保证不会写入或删除数据但数据外发本身仍需人工评估所有工具响应均以 LLM 友好的 JSON 返回可通过tempo_query_frontend_mcp_calls_total指标观测各工具的调用量。八、总结Tempo 的 MCP 服务器把链路检索、TraceQL 指标计算、链路对比、属性发现与文档查询统一封装为 MCP 工具和资源让 AI 助手能在对话中直接、按需地获取分布式追踪数据与查询语法。它以 YAML 或命令行 flag 一键启用通过 Streamable HTTP 对外提供/api/mcp端点并完整复用 Tempo 既有的查询管线、认证与多租户能力。本文介绍的 9 个工具、7 个资源及 trace-diff 的三种输出格式均可对照 modules/frontend/mcp.go 与 modules/frontend/mcp_tools.go 源码进一步深入或参考官方文档 docs/sources/tempo/api_docs/mcp-server.md 与 docs/sources/tempo/introduction/tempo-and-ai.md 获取更多上下文。【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考