内容
# jaeger-mcp
<!-- mcp-name: io.github.mshegolev/jaeger-mcp -->
[](https://pypi.org/project/jaeger-mcp/)
[](https://pypi.org/project/jaeger-mcp/)
[](LICENSE)
[](https://github.com/mshegolev/jaeger-mcp/actions/workflows/test.yml)
**适用于 [Jaeger](https://www.jaegertracing.io/) 的 MCP 服务器，用于分布式追踪。**
赋予 Claude（或任何支持 MCP 的代理）对跟踪数据的读取权限 - 搜索跟踪，检查跨度，比较跟踪，计算跨度统计数据，映射服务依赖关系，预测性能问题，并预测容量需求 - 无需离开对话。
## 为什么有另一个 Jaeger MCP？
现有的 Jaeger 集成需要运行的 UI 或自定义脚本。此服务器：
- 通过 **stdio** 使用标准 [模型上下文协议](https://modelcontextprotocol.io/) - 与 Claude Desktop、Claude Code、Cursor 和任何 MCP 客户端配合使用。
- 是 **只读** 的：所有 12 种工具都带有 `readOnlyHint: true` - 零风险修改跟踪数据。
- 返回 **双通道输出**：用于编程的 structured JSON（`structuredContent`）+ 用于人类可读显示的 Markdown（`content`）。
- 具有 **可操作的错误消息**，命名确切的 env var 进行修复并建议下一步。
- 支持 **Bearer token**，**HTTP 基本身份验证** 或 **无身份验证**（常见于内部部署）。
- 包括 **OpenAPI 规范**，记录底层 Jaeger 查询 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}` | 完整的跟踪详细信息，带有跨度树 |
| `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}` | 最长持续时间跨度链和瓶颈排名 |
| `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` | 预测吞吐量需求和资源需求 |
## 安装
```bash
pip install jaeger-mcp
```
或直接运行而无需安装：
```bash
uvx jaeger-mcp
```
## 配置
所有配置均通过环境变量进行：
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `JAEGER_URL` | **是** | — | Jaeger 查询服务 URL，例如 `https://jaeger.example.com` |
| `JAEGER_TOKEN` | 否 | — | Bearer token（优先于基本身份验证） |
| `JAEGER_USERNAME` | 否 | — | HTTP 基本身份验证用户名 |
| `JAEGER_PASSWORD` | 否 | — | HTTP 基本身份验证密码 |
| `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`）中添加：
```json
{
"mcpServers": {
"jaeger": {
"command": "jaeger-mcp",
"env": {
"JAEGER_URL": "https://jaeger.example.com",
"JAEGER_TOKEN": "your-token-here"
}
}
}
}
```
或使用 `uvx`（无需安装）：
```json
{
"mcpServers": {
"jaeger": {
"command": "uvx",
"args": ["jaeger-mcp"],
"env": {
"JAEGER_URL": "https://jaeger.example.com"
}
}
}
}
```
## Docker
```bash
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` - 哪些跨度发生了变化？"
- " `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 个字符）并返回：
- 带有标签，服务名称，父/子关系的跨度
- 服务统计信息（跨度计数，总时长，错误计数）
- 执行树（每个节点列出其子跨度 ID）
错误跨度由 `tags["error"] = "true"` 标识。
### `jaeger_get_dependencies`
服务拓扑图。返回带有 `call_count` 的有向边（`parent → child`）。使用 `lookback_hours`（默认 24，最大 720）控制窗口。
### `jaeger_compare_traces`
两个跟踪之间的结构差异。接受两个 `trace_id` 十六进制字符串，并通过 `(operationName, serviceName, parentOperation)` 匹配跨度 - 而不是跨度 ID。报告：
- **添加的跨度** - 在跟踪 B 中存在但在跟踪 A 中不存在
- **删除的跨度** - 在跟踪 A 中存在但在跟踪 B 中不存在
- **更改的跨度** - 匹配但在持续时间或标签上有所不同（显示增量）
- **未更改计数** - 相同的跨度数量
用于比较慢速跟踪和快速跟踪，或查看部署之间发生了什么变化。
### `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`
扫描服务的最近跟踪中是否存在统计学上显著的延迟峰值或错误率增加，与历史基线相比。
报告：
- 标记的运算，带有异常类型（延迟或错误率）
- 严重性分类（低至严重），带有 z 分数
- 受影响指标的当前值与基线值
用于主动识别性能下降和可靠性问题，在它们影响用户之前。
## 库 facade（进程内使用）
`jaeger-mcp` 还可以作为 Python 库使用，无需 MCP 服务器：
```python
from jaeger_mcp import JaegerClient
client = JaegerClient.from_env() # 从 env 读取 JAEGER_URL
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()`。
领域对象：`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` 聚合整个观察窗口；大窗口在繁忙的集群上可能较慢。
## 开发
```bash
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](LICENSE)。
