# ISS-0086: Agent 未将 PD TSO Wait Duration 纳入延迟归因分析

## Background

TCID-12704（cluster 10123293495242577103，2026-05-13 14:35 JST）：用户通过 GitHub issue #561
提问："Please consider PD client metrics too. I observed PD TSO Wait Duration was growing during
the incident. Do you think it was a symptom or a cause?"

在 TCID-12704 postmortem 中，Agent 诊断结论聚焦于：
- `coupon_attached_items` 查询 CPU 饱和（主因）
- scale-in 34→33 导致 TCP 连接断开（客户断连根因）

但 Agent 未分析 PD TSO Wait Duration 指标，无法回答用户的问题：
TSO 等待延迟升高是查询延迟的独立原因，还是 TiDB CPU 饱和的下游症状？

## Root Cause Analysis

当 TiDB CPU 饱和（75%）时，TiDB server 的 TSO 请求处理线程也会被挤占，
导致 PD TSO Wait Duration 升高——这是**症状**，不是**根因**。

但在 scale-in 发生后（34→33），PD leader 需要服务的 TiDB 节点不变（33 vs 34 差异极小），
TSO 吞吐量通常不受显著影响。若 TSO Wait Duration 持续高企，需要区分：

1. **TiDB 侧**：TiDB CPU 饱和 → TSO 获取任务排队 → TSO Wait Duration 高
2. **PD 侧**：PD leader 本身性能问题（磁盘 I/O、leader 切换）→ TSO 响应慢
3. **网络侧**：TiDB→PD 网络延迟升高

正确的诊断路径：
- 对比 TSO Wait Duration 峰值时间点 vs CPU 饱和时间点（若同步 → 症状）
- 查询 PD 自身 CPU/内存指标（若 PD 正常 → 客户端侧排队）
- 检查 PD leader 是否在事故期间切换（切换 → 可能是独立原因）

## Observed Error

在 TCID-12704 的 prod workspace（ws-1779071696491-aabaf929c）和 local replay workspace
（ws-1779156165000-34f5ef8b3）中，Agent 均未查询 PD TSO 相关指标：
- `pd_server_tso_handle_duration`（TSO 处理延迟）
- `pd_client_request_handle_requests_duration_seconds`（PD 客户端请求延迟）
- `pd_client_cmd_handle_cmds_duration_seconds`（PD 命令延迟）

因此在 postmortem 结论中无法区分"TSO 高是 CPU 饱和的下游症状"vs"TSO 高是独立根因"。

## Fix Plan

### Step 1: 在 SKILL.md 增加 PD TSO 延迟分析规则

在 Node C（App-layer Triage）延迟诊断部分增加：

```markdown
**PD TSO Wait Duration 分析**（当 query_time >> process_time 时适用）：
- 若 evidence_summary 中没有 PD TSO 指标，通过 Clinic metrics API 补充查询：
  - `pd_client_cmd_handle_cmds_duration_seconds{type="tso"}`（P99，事故窗口）
  - `pd_server_tso_handle_duration`（PD server 端处理延迟）
- 判断规则：
  1. TSO 高 + PD CPU 正常 + TiDB CPU 高 → TSO 是 CPU 饱和的下游症状（不是独立根因）
  2. TSO 高 + PD CPU 高或 PD leader 切换 → PD 可能是独立因素
  3. TSO 高 + scale-in 期间 → 检查 PD leader 是否参与 scale-in，通常不影响 TSO
- 输出结论中应明确：TSO Wait Duration 是症状还是独立根因
```

### Step 2: collect_evidence.py 补充 PD TSO 指标采集

在 A1 段（metrics 采集）中增加 PD TSO 相关指标：
```python
# A1: PD TSO 延迟
metrics_to_collect.extend([
    "histogram_quantile(0.99, pd_client_cmd_handle_cmds_duration_seconds_bucket{type='tso'})",
    "pd_server_tso_handle_duration",
])
```

写入 `pd_tso_duration` 字段到 evidence_summary。

### Step 3: 验证

使用 TCID-12704 workspace 验证：
1. evidence_summary 包含 PD TSO Wait Duration 数据
2. Agent 诊断输出明确说明"TSO 高是 CPU 饱和的下游症状，不是独立根因"
3. 诊断输出能回答用户的问题："Is PD TSO Wait Duration a symptom or a cause?"

## Files to Modify

- `agentkit/skills/builtin/tidb-clinic-diagnosis/SKILL.md`
  - Node C 延迟分析部分增加 PD TSO Wait Duration 分析规则
- `agentkit/skills/builtin/tidb-clinic-diagnosis/scripts/collect_evidence.py`
  - A1 段增加 PD TSO 指标采集