AI导哈

轨迹查询服务器

Tempo MCP Server是一个高级模型上下文协议(MCP)服务器，用于查询Grafana Tempo轨迹和跨度，具有全面的过滤功能。

  • by UjjwalSk
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 UjjwalSk/tempo-mcp-server

使用说明

Tempo MCP 服务器

一个高级的模型上下文协议（MCP）服务器，用于查询Grafana Tempo中的追踪和跨度，并具备全面的过滤功能。

特点/特性

  • 灵活轨迹搜索使用TraceQL或旧版标签查询追踪记录
  • 跨度过滤按服务名称、持续时间、属性、错误过滤跨度
  • 详细跨度分析获取包含计算时长的完整跨度详情
  • 跨度统计按服务/操作/状态分组的汇总统计
  • 基于标签的查询通过自定义标签轻松筛选
  • 时间范围支持按绝对或相对时间范围查询
  • 持续时间过滤在追踪（trace）和跨度（span）级别按最小/最大持续时间过滤

安装

cd ~/tempo-mcp-server
npm install
npm run build

配置

环境变量

创建一个 .env 文件或设置环境变量：

# Required
TEMPO_URL=http://localhost:3200

# Optional
TEMPO_USERNAME=admin
TEMPO_PASSWORD=secret
TEMPO_TOKEN=bearer_token_here
TEMPO_TIMEOUT=30000

Claude 桌面配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "tempo-mcp": {
      "command": "node",
      "args": ["[YOUR-PROJECT-PATH]/dist/index.js"],
      "env": {
        "TEMPO_URL": "http://localhost:3200"
      }
    }
  }
}

可用工具

1. tempo_search_traces

使用灵活的过滤选项搜索记录。

参数：

  • query (字符串)：TraceQL 查询（例如。， {.service.name="app-demo"})
  • tags （字符串）：旧版标签格式（例如。， service.name=app-demo）
  • minDuration （字符串）：最小持续时间（例如，“100ms”，“1s”）
  • maxDuration (字符串)：最大持续时间（例如，“5s”）
  • limit (数字)：返回的最大追踪数（默认：20）
  • start (字符串)：开始时间（RFC3339 格式或 Unix 时间戳）
  • end (字符串)：结束时间（RFC3339 格式或 Unix 时间戳）

示例：

{
  "query": "{.service.name=\"app-demo\" && span.http.status_code >= 400}",
  "minDuration": "100ms",
  "limit": 50,
  "start": "2025-01-01T00:00:00Z"
}

2. tempo_get_trace

通过ID获取完整的追踪数据。

参数：

  • traceId （字符串，必填）：追踪ID

3. tempo_get_trace_spans

从一个追踪中获取所有跨度，并可选择进行过滤。

参数：

  • traceId （字符串，必填）：追踪ID
  • serviceName (字符串)：按服务名称过滤
  • spanName (字符串)：按跨度名称过滤（部分匹配）
  • minDuration (数字)：最小跨度持续时间（毫秒）
  • maxDuration (数字)：最大跨度时长（毫秒）
  • hasError (boolean): 仅过滤错误跨度
  • attributes (对象)：按属性过滤（例如。， {"http.method": "POST"})

示例：

{
  "traceId": "1c4090cb9c90630901b167ad22c769aa",
  "serviceName": "app-demo",
  "minDuration": 100,
  "attributes": {
    "http.method": "POST"
  }
}

4. tempo_search_spans

搜索追踪记录，并返回多个追踪记录中匹配的片段。

参数：

  • 追踪搜索参数： query， tags， minDuration， maxDuration， limit， start， end
  • 跨度过滤参数： serviceName， spanName， spanMinDuration， spanMaxDuration， spanHasError， spanAttributes

示例：

{
  "query": "{.service.name=\"app-demo\"}",
  "limit": 10,
  "spanName": "POST",
  "spanMinDuration": 1000
}

5. tempo_get_span_statistics

获取聚合的跨度统计信息。

参数：

  • 搜索参数： query， tags， limit， start， end
  • groupBy (字符串): "服务"、"操作" 或 "状态"

返回值：

  • 每组的计数、平均/最小/最大持续时间，以及p50/p95/p99百分位数

示例：

{
  "query": "{.service.name=\"app-demo\"}",
  "limit": 100,
  "groupBy": "service"
}

6. tempo_query_by_tag

通过自定义标签过滤器查询追踪记录（便捷方法）。

参数：

  • tagFilters （对象，必需）：标签键值对
  • serviceName (字符串)：服务名称过滤器
  • minDuration， maxDuration， limit， start， end

示例：

{
  "tagFilters": {
    "customtag": "tagValue",
    "environment": "production"
  },
  "limit": 20
}

使用示例

示例1：查找自定义标签的所有踪迹

tempo_query_by_tag({
  tagFilters: { "customtag": "tagValue" },
  start: "2025-01-01T00:00:00Z",
  end: "2025-01-02T00:00:00Z"
})

示例2：获取详细的跨度细分

tempo_get_trace_spans({
  traceId: "abc123...",
  serviceName: "app-demo"
})

示例3：查找缓慢的数据库操作

tempo_search_spans({
  query: "{.service.name=\"app-demo\"}",
  spanName: "SELECT",
  spanMinDuration: 1000  // > 1 second
})

示例4：获取服务性能统计信息

tempo_get_span_statistics({
  query: "{.service.name=\"app-demo\"}",
  start: "2025-01-01T00:00:00Z",
  groupBy: "operation"
})

示例5：在时间范围内查找错误

tempo_search_traces({
  query: "{span.http.status_code >= 400}",
  start: "1704067200",  // Unix timestamp
  limit: 50
})

TraceQL 查询示例

// By service name
{.service.name="app-demo"}

// By tag
{.customtag="tagValue"}

// HTTP status codes
{span.http.status_code >= 400}

// Duration
{duration > 1s}

时间格式示例

// RFC3339
"2025-01-01T00:00:00Z"
"2025-01-01T00:00:00+05:30"

// Unix timestamp (seconds)
"1704067200"
1704067200

// Relative (in TraceQL)
"now-1h"
"now-24h"

发展

# Watch mode
npm run watch

# Build
npm run build

# Run
npm start

故障排除

连接问题

  • 验证 TEMPO_URL 是正确的
  • 检查Tempo是否正在运行： curl http://localhost:3200/api/status
  • 检查防火墙/网络连接

查询错误

  • 验证 TraceQL 语法 - 查询必须用（特定的符号或结构）包裹 {}
  • 检查时间范围是否有效（RFC3339 格式或 Unix 时间戳）
  • 确保追踪ID的格式正确（十六进制字符串）
  • 使用 resource.service.name 而不是 .service.name 用于服务过滤
  • 为了调试，请设置 TEMPO_DEBUG=true 在环境中

演出

  • 减少 limit 用于加快查询的参数
  • 狭窄的时间范围
  • 使用特定过滤器来减少数据量

相关 MCP