名称: jaeger-analysis 描述: Jaeger 分布式追踪分析。在调查请求延迟、追踪跨服务错误、查找慢速跨度或理解服务依赖时使用。允许工具: Bash(python *)

Jaeger 追踪分析

认证

重要: 凭证通过代理层自动注入。不要检查环境变量中的 JAEGER_URL 或其他凭证——它们对你不可见。直接运行脚本；认证透明处理。

可检查的配置环境变量（非机密）：

JAEGER_URL - Jaeger 查询 API URL（例如，http://jaeger-query:16686）

强制性：统计优先调查

绝不转储所有追踪。始终遵循此模式：

服务 → 操作 → 统计 → 样本追踪

列出服务 - 了解存在的服务
列出操作 - 理解每个服务的端点/操作
获取统计 - 错误率、延迟百分位数
样本追踪 - 了解情况后获取特定追踪

可用脚本

所有脚本位于 .claude/skills/observability-jaeger/scripts/

服务发现

list_services.py - 列出所有追踪服务

python .claude/skills/observability-jaeger/scripts/list_services.py

# 输出: 发送追踪到 Jaeger 的所有服务列表

list_operations.py - 列出服务的操作

python .claude/skills/observability-jaeger/scripts/list_operations.py <service>

# 示例:
python .claude/skills/observability-jaeger/scripts/list_operations.py frontend

追踪调查

get_traces.py - 搜索追踪

python .claude/skills/observability-jaeger/scripts/get_traces.py --service SERVICE [选项]

# 选项:
#   --operation OPERATION  按操作名称过滤
#   --tags KEY=VALUE       按标签过滤（可重复）
#   --min-duration MS      最小持续时间（毫秒）
#   --max-duration MS      最大持续时间（毫秒）
#   --limit N              最大返回追踪数（默认: 20）
#   --lookback HOURS       回溯搜索时间（默认: 1）

# 示例:
python .claude/skills/observability-jaeger/scripts/get_traces.py --service frontend --limit 10
python .claude/skills/observability-jaeger/scripts/get_traces.py --service checkout --min-duration 500
python .claude/skills/observability-jaeger/scripts/get_traces.py --service api --operation "HTTP GET /users" --limit 5
python .claude/skills/observability-jaeger/scripts/get_traces.py --service payment --tags error=true

get_trace.py - 按 ID 获取完整追踪

python .claude/skills/observability-jaeger/scripts/get_trace.py <trace-id>

# 示例:
python .claude/skills/observability-jaeger/scripts/get_trace.py abc123def456789

延迟分析

get_slow_traces.py - 查找慢速追踪

python .claude/skills/observability-jaeger/scripts/get_slow_traces.py --service SERVICE [选项]

# 选项:
#   --min-duration MS      最小持续时间阈值（默认: 1000）
#   --operation OPERATION  按特定操作过滤
#   --limit N              最大返回追踪数（默认: 20）
#   --lookback HOURS       回溯搜索时间（默认: 1）

# 示例:
python .claude/skills/observability-jaeger/scripts/get_slow_traces.py --service checkout --min-duration 500
python .claude/skills/observability-jaeger/scripts/get_slow_traces.py --service api --operation "POST /orders"

get_latency_stats.py - 延迟统计

python .claude/skills/observability-jaeger/scripts/get_latency_stats.py --service SERVICE [选项]

# 选项:
#   --operation OPERATION  按操作过滤
#   --lookback HOURS       时间窗口（默认: 1）

# 示例:
python .claude/skills/observability-jaeger/scripts/get_latency_stats.py --service frontend
python .claude/skills/observability-jaeger/scripts/get_latency_stats.py --service checkout --operation "POST /checkout"

错误分析

get_error_traces.py - 查找错误追踪

python .claude/skills/observability-jaeger/scripts/get_error_traces.py --service SERVICE [选项]

# 选项:
#   --operation OPERATION  按操作过滤
#   --limit N              最大追踪数（默认: 20）
#   --lookback HOURS       时间窗口（默认: 1）

# 示例:
python .claude/skills/observability-jaeger/scripts/get_error_traces.py --service payment
python .claude/skills/observability-jaeger/scripts/get_error_traces.py --service api --operation "POST /checkout"

调查工作流

标准延迟调查

┌─────────────────────────────────────────────────────────────┐
│ 1. 列出服务                                              │
│    python list_services.py                                    │
│    → 识别要调查的服务                                        │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. 获取延迟统计                                          │
│    python get_latency_stats.py --service X                    │
│    → 查看每个操作的 p50、p95、p99 延迟                    │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
                   发现高延迟？
               ┌─────────────┴─────────────┐
               │                           │
              是                          否
               │                           │
               ▼                           ▼
┌─────────────────────────────┐  ┌───────────────────────────────────────────┐
│ 3a. 获取慢速追踪          │  │ 3b. 检查错误                          │
│    python get_slow_traces.py│  │    python get_error_traces.py --service X │
│    --service X              │  │    → 查找错误模式                      │
│    → 分析慢速路径          │  └───────────────────────────────────────────┘
└─────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. 分析特定追踪                                          │
│    python get_trace.py <trace-id>                             │
│    → 查看完整跨度树，找到瓶颈                              │
└─────────────────────────────────────────────────────────────┘

快速命令参考

目标	命令
列出所有服务	`list_services.py`
列出操作	`list_operations.py <service>`
获取延迟统计	`get_latency_stats.py --service X`
查找慢速追踪	`get_slow_traces.py --service X --min-duration 500`
查找错误追踪	`get_error_traces.py --service X`
获取特定追踪	`get_trace.py <trace-id>`
按标签搜索	`get_traces.py --service X --tags http.status_code=500`

追踪结构

跨度结构

追踪 (trace_id: abc123)
├── 跨度: frontend (span_id: 001, 持续时间: 250ms)
│   ├── 跨度: api-gateway (span_id: 002, 持续时间: 200ms)
│   │   ├── 跨度: auth-service (span_id: 003, 持续时间: 50ms)
│   │   └── 跨度: order-service (span_id: 004, 持续时间: 120ms) ← 瓶颈
│   │       └── 跨度: database (span_id: 005, 持续时间: 100ms) ← 根本原因
│   └── 跨度: cache-lookup (span_id: 006, 持续时间: 5ms)

常见标签

http.method - HTTP 方法（GET、POST 等）
http.url - 请求 URL
http.status_code - 响应状态码
error - 布尔值，如果跨度有错误则为 true
span.kind - client、server、producer、consumer
db.type - 数据库类型（mysql、postgres、redis）
db.statement - 数据库查询（可能被截断）

查找瓶颈

按持续时间排序跨度（从最长开始）
查找关键路径（主要请求流上的跨度）
检查慢速跨度是否有子跨度（慢速子跨度 = 传播延迟）
检查标签是否有 error=true 或高状态码

常见模式

查找慢速数据库查询

# 查找有慢速数据库操作的追踪
python .claude/skills/observability-jaeger/scripts/get_traces.py \
  --service order-service \
  --tags db.type=postgres \
  --min-duration 100

查找 HTTP 错误

# 查找 5xx 错误
python .claude/skills/observability-jaeger/scripts/get_traces.py \
  --service api-gateway \
  --tags http.status_code=500

# 或使用错误追踪脚本
python .claude/skills/observability-jaeger/scripts/get_error_traces.py --service api-gateway

比较跨服务延迟

# 获取每个服务的统计
python .claude/skills/observability-jaeger/scripts/get_latency_stats.py --service frontend
python .claude/skills/observability-jaeger/scripts/get_latency_stats.py --service api
python .claude/skills/observability-jaeger/scripts/get_latency_stats.py --service database

避免的反模式

绝不获取所有追踪 - 始终使用过滤器（服务、时间、持续时间）
跳过服务发现 - 始终从 list_services.py 开始
忽略延迟统计 - 在深入单个追踪前获取百分位数
关注单跨度 - 查看完整追踪上下文
遗漏错误标签 - 始终检查慢速追踪中的 error=true
无边界时间范围 - 始终指定 --lookback 限制时间

输出格式

报告追踪发现时，使用此结构：

## 追踪分析摘要

### 服务: [服务名称]
### 时间窗口: [开始] 到 [结束]

### 延迟统计
| 操作 | p50 | p95 | p99 | 计数 |
|-----------|-----|-----|-----|-------|
| GET /api  | 50ms| 150ms| 300ms| 1000|

### 发现慢速追踪
1. **追踪 ID**: abc123
   - **持续时间**: 2.5s
   - **瓶颈**: database 跨度 (1.8s)
   - **根本原因**: orders 表上的慢速查询

### 发现错误追踪
1. **追踪 ID**: def456
   - **错误**: 到 payment-service 的连接被拒绝
   - **影响**: 返回客户端的 5xx

### 根本原因假设
[基于追踪分析]

### 推荐操作
[具体补救步骤]

名称: jaeger-analysis 描述: Jaeger 分布式追踪分析。在调查请求延迟、追踪跨服务错误、查找慢速跨度或理解服务依赖时使用。 允许工具: Bash(python *)

Jaeger 追踪分析

认证

强制性：统计优先调查

可用脚本

服务发现

list_services.py - 列出所有追踪服务

list_operations.py - 列出服务的操作

追踪调查

get_traces.py - 搜索追踪

get_trace.py - 按 ID 获取完整追踪

延迟分析

get_slow_traces.py - 查找慢速追踪

get_latency_stats.py - 延迟统计

错误分析

get_error_traces.py - 查找错误追踪

调查工作流

标准延迟调查

快速命令参考

追踪结构

跨度结构

常见标签

查找瓶颈

常见模式

查找慢速数据库查询

查找 HTTP 错误

比较跨服务延迟

避免的反模式

输出格式

名称: jaeger-analysis 描述: Jaeger 分布式追踪分析。在调查请求延迟、追踪跨服务错误、查找慢速跨度或理解服务依赖时使用。允许工具: Bash(python *)