jaeger-mcp

jaeger-mcp

用于 Jaeger 分布式追踪的 MCP 服务。 让 Claude（或任何支持 MCP 的 Agent）读取你的追踪数据——搜索追踪记录、检查 span、比较追踪记录、计算 span 统计信息、映射服务依赖关系、预测性能问题并预估容量需求——无需离开对话。

为什么还需要另一个 Jaeger MCP？

现有的 Jaeger 集成需要运行中的 UI 或自定义脚本。此服务：

• 通过 stdio 使用标准的 Model Context Protocol——适用于 Claude Desktop、Claude Code、Cursor 和任何 MCP 客户端。
• 只读：全部 15 个工具均带有 readOnlyHint: true——完全没有修改追踪数据的风险。
• 返回双通道输出：供程序使用的结构化 JSON（structuredContent）+ 供人阅读的 Markdown（content）。
• 提供可执行的错误消息，指出需要修正的确切环境变量并建议后续步骤。
• 支持 Bearer token、HTTP Basic auth 或无身份验证（内部部署的常见方式）。
• 附带 OpenAPI 规范，用于说明底层 Jaeger Query API（openapi.yaml）。

工具

工具	端点	描述
jaeger_list_services	GET /api/services	列出所有已插桩的服务
jaeger_list_operations	GET /api/services/{service}/operations	列出某个服务的操作名称
jaeger_search_traces	GET /api/traces	使用丰富的筛选条件搜索追踪记录
jaeger_get_trace	GET /api/traces/{traceID}	包含 span 树的完整追踪详情
jaeger_get_dependencies	GET /api/dependencies	服务间调用图
jaeger_compare_traces	GET /api/traces/{traceID} ×2	比较两个追踪记录的结构差异
jaeger_span_statistics	GET /api/traces	按操作统计延迟和错误
jaeger_critical_path	GET /api/traces/{traceID}	持续时间最长的 span 链及瓶颈排名
jaeger_compare_windows	GET /api/traces ×2	比较两个时间段内的追踪行为汇总差异
jaeger_detect_anomalies	GET /api/traces ×2	按操作检测延迟／错误率的统计尖峰
jaeger_predict_degradation	GET /api/traces	提前 2-24 小时预测性能退化
jaeger_forecast_capacity	GET /api/traces	预测吞吐量需求和资源要求
jaeger_find_test_traces	GET /api/traces	通过标签查询（Allure/pytest/自定义）将测试运行与其追踪记录关联起来
jaeger_regression_diff	GET /api/traces ×2	对两个时间窗口之间各操作的回归进行分类
jaeger_test_profile	GET /api/traces	统计带标签测试运行中各操作的延迟热点

安装

pip install jaeger-mcp

也可以直接运行，无需安装：

uvx jaeger-mcp

配置

所有配置均通过环境变量完成：

变量	必填	默认值	描述
JAEGER_URL	是	—	Jaeger 查询服务 URL，例如 https://jaeger.example.com
JAEGER_TOKEN	否	—	Bearer 令牌（优先于 Basic 身份验证）
JAEGER_USERNAME	否	—	HTTP Basic 身份验证用户名
JAEGER_PASSWORD	否	—	HTTP Basic 身份验证密码
JAEGER_SSL_VERIFY	否	true	使用自签名证书时设为 false
JAEGER_TIMEOUT	否	30	HTTP 请求超时时间，单位为秒
JAEGER_RETRY_ATTEMPTS	否	3	暂时性故障的重试次数（设为 0 可禁用）
JAEGER_CACHE_TTL	否	120	发现端点缓存的 TTL，单位为秒（设为 0 可禁用）

将 .env.example 复制为 .env，并填入你的值。

Claude Desktop / Claude Code 设置

将以下内容添加到 MCP 配置（claude_desktop_config.json 或 .claude/mcp.json）：

{
  "mcpServers": {
    "jaeger": {
      "command": "jaeger-mcp",
      "env": {
        "JAEGER_URL": "https://jaeger.example.com",
        "JAEGER_TOKEN": "your-token-here"
      }
    }
  }
}

或者使用 uvx（无需安装）：

{
  "mcpServers": {
    "jaeger": {
      "command": "uvx",
      "args": ["jaeger-mcp"],
      "env": {
        "JAEGER_URL": "https://jaeger.example.com"
      }
    }
  }
}

Docker

docker run --rm -e JAEGER_URL=https://jaeger.example.com jaeger-mcp

示例查询

配置完成后，可以向 Claude 提问：

• “Jaeger 知道哪些服务？”
• “查找过去一小时 order-service 中出现 HTTP 500 错误的追踪记录”
• “显示 GET /checkout 耗时最长的追踪记录（超过 2 秒）”
• “追踪记录 abcdef1234567890 中的错误是什么原因导致的？”
• “绘制过去 7 天的服务依赖图”
• “哪些服务最频繁地调用 postgres？”
• “比较追踪记录 abc123 和 def456——哪些 span 发生了变化？”
• “order-service 中各操作的 p95 延迟是多少？”

工具使用指南

jaeger_list_services

返回 Jaeger 记录过的所有服务名称。如果不知道哪些服务已接入监控，请从这里开始。输出最多包含 500 个服务，并会提示结果已截断。

jaeger_list_operations

返回指定服务的所有操作名称（例如 HTTP 路由名称、gRPC 方法名称）。在使用 jaeger_search_traces 筛选之前，可用此工具发现有效的操作名称。

jaeger_search_traces

主要搜索工具。筛选条件：

• service（必填）——来自 jaeger_list_services 的服务名称
• operation ——限定到特定端点
• tags ——标签筛选条件的 JSON 字符串，例如 {"http.status_code":"500"} 或 {"error":"true"}
• start / end ——时间范围，单位为 UTC 微秒
• min_duration / max_duration ——时长字符串，例如 "100ms"、"1.5s"、"2m"
• limit ——默认值为 20，最大值为 1500

返回追踪摘要，包含 trace_id、duration_us、span_count、service_count、root_operation、errors_count。

jaeger_get_trace

返回完整的追踪详情。接受一个 trace_id（16–32 个字符的十六进制字符串），并返回：

• 所有 span 及其标签、服务名称、父子关系
• 各服务的统计信息（span 数量、总时长、错误数量）
• 执行树（每个节点列出其子 span ID）

错误 span 会标记为 tags["error"] = "true"。

jaeger_get_dependencies

返回服务拓扑图，包含带有 call_count 的有向边 (父级 → 子级)。使用 lookback_hours（默认值为 24，最大值为 720）控制时间范围。

jaeger_compare_traces

比较两条追踪记录的结构差异。接受两个 trace_id 十六进制字符串，并按 (operationName, serviceName, parentOperation) 匹配 span，而非按 span ID 匹配。报告内容包括：

• 新增 span——存在于追踪记录 B 中，但不存在于追踪记录 A 中
• 已移除 span——存在于追踪记录 A 中，但不存在于追踪记录 B 中
• 已更改 span——匹配成功，但时长或标签不同（显示差异）
• 未更改数量——完全相同的 span 数量

可用于比较慢速和快速的追踪记录，或查看不同部署之间的变化。

jaeger_span_statistics

各操作的延迟百分位数和错误率。获取某个服务最多 limit 条跟踪记录（默认 20，最多 100），并按操作名称聚合所有跨度。报告各操作的：

• count — 观察到的跨度总数
• p50_duration_us、p95_duration_us、p99_duration_us — 延迟百分位数
• error_count、error_rate — 错误数（通过 tags["error"] = "true" 识别）

可用于找出服务中耗时最长或最容易出错的操作。

jaeger_critical_path

识别跟踪记录中从根节点到叶节点的最长跨度链（关键路径），并按自身耗时对跨度排序，以查找性能瓶颈。

报告：

• 关键路径跨度，包括操作、服务、耗时和占总耗时的百分比
• 按独占耗时（自身耗时）排序的瓶颈跨度

可用于回答“这条跟踪记录为什么这么慢？”以及“哪些操作消耗的 CPU/自身耗时最多？”

jaeger_compare_windows

比较某个服务在两个时间段内的跟踪记录汇总行为，以检测不同部署之间的性能回退或改善。

报告：

• 各操作的差异摘要，显示新增、移除、加快和变慢的操作
• 偏差评分，包含各操作和整体的数值评分
• 延迟百分位数（p50、p95）的变化以及错误率差值

可用于回答“最新部署是否影响了性能？”以及“数据库升级后哪些操作变慢了？”

jaeger_detect_anomalies

扫描某个服务近期的跟踪记录，找出与历史基线相比具有统计显著性的延迟峰值或错误率上升。

报告：

• 标记的操作及异常类型（延迟或 error_rate）
• 严重性分类（从低到严重），并附 z 分数
• 受影响指标的当前值与基线值

可用于主动发现性能下降和可靠性问题，避免问题影响用户。

库封装（进程内使用）

jaeger-mcp 也可作为 Python 库使用，无需 MCP 服务：

from jaeger_mcp import JaegerClient

client = JaegerClient.from_env()  # reads JAEGER_URL from env
trace = client.get_trace("abcdef1234567890abcdef1234567890")

for span in trace.spans:
    if span.error:
        print(f"{span.service_name}: {span.operation} at {span.start_utc}")
        print(f"  tags: {span.tags}")

可用方法：get_trace()、search_traces()、list_services()、get_dependencies()、compare_traces()、span_statistics()、critical_path()、compare_windows()、detect_anomalies()、predict_degradation()、forecast_capacity()、find_test_traces()、regression_diff()、test_profile()。

领域对象：Span、Trace、TraceSummary、ServiceDep、TraceComparison、SpanIdentity、SpanChange、SpanStatisticsResult、OperationStatResult、CriticalPathOutput、CriticalPathSpan、BottleneckSpan、WindowComparisonOutput、OperationDiff、AnomalyDetectionOutput、OperationAnomaly——均带有类型化字段。

API 文档

此项目在 docs/ 目录中包含全面的 OpenAPI 规范：

1. Jaeger 查询服务 API（openapi.yaml）——记录实际的 Jaeger API 端点
2. MCP 工具 API（docs/mcp-tools-openapi.yaml）——将 MCP 工具记录为概念性的 HTTP 端点

这些规范有助于：

• 了解各工具发出的底层 API 调用
• 开发其他集成方式
• 调试 API 交互
• 生成客户端库或文档

有关这两种规范的更多详情，请参阅 docs/README.md。

性能特征

• 所有工具都使用同一个持久化的 requests.Session，并启用连接池。
• 会话的 trust_env = False，以绕过环境代理（Jaeger 通常是内部服务）。
• 请求在 30 秒后超时（可通过 JAEGER_TIMEOUT 配置）。
• 瞬时 HTTP 错误（429/5xx）会以指数退避方式重试（可通过 JAEGER_RETRY_ATTEMPTS 配置）。
• list_services 和 list_operations 的响应会缓存 120 秒（可通过 JAEGER_CACHE_TTL 配置）。
• jaeger_search_traces 会将 limit 直接传递给 Jaeger，请避免请求超出所需数量的链路追踪。
• jaeger_get_trace 会通过一次调用获取完整链路追踪；大型链路追踪（包含数千个跨度）可能会比较慢。
• jaeger_get_dependencies 会汇总整个回溯时间范围内的数据；在繁忙的集群上，较大的时间范围可能会比较慢。

开发

git clone https://github.com/mshegolev/jaeger-mcp
cd jaeger-mcp
pip install -e '.[dev]'
pytest tests/ -v
ruff check src tests
ruff format src tests

许可证

MIT — 参见 LICENSE。