# ISS-0112 Plan: Agent 将网络层延迟问题归因为业务/查询层问题

## Background

**Workspace**: ws-1783480020792-e22cbc2ee (prod: investibook.com)
**Case**: wetech saas01 集群 P999 延迟异常（10:43 时 P999 上升到 2s）
**User feedback**: "根因彻底归因错误，是一个网络问题，而不是业务问题"

用户报告 P999 延迟突升至 2s，Agent 将根因归结为业务层（查询/负载）问题，
但实际根因是网络层问题（如 TiKV 节点间网络抖动、gRPC 网络延迟飙升、跨 AZ 网络故障等）。
Agent 缺乏对延迟突升场景进行系统性网络层排查的决策规则。

## Pattern

P999 延迟突升 → Agent 优先查 TopSQL/SlowQuery/CPU → 发现高 CPU/热点 SQL → 归因为查询问题
却未检查：
- TiKV gRPC network latency 指标（`tikv_grpc_msg_duration_seconds`）
- TiDB→TiKV network round-trip（`tikv_server_grpc_req_batch_recv_latency`）
- TiDB 内部等待：process_time vs wait_time 比例（wait_time >> process_time → IO/网络等待）
- 网络分区或跨 AZ 延迟（`tikv_server_raft_message_duration` 等）

## Root Cause Analysis

SKILL.md Node C/D 中缺少对"网络层 vs 查询层"的鉴别规则：

1. **wait_time >> process_time** 是网络/IO 等待的首要信号（ISS-0068 已部分覆盖此场景，
   但 ISS-0068 关注 EBS IOPS 节流，未覆盖纯网络延迟场景）。
2. 当 P999 延迟突升但 TopSQL CPU 无明显异常时，Agent 应优先检查网络层指标，
   而非继续深挖 SQL 执行计划。
3. 网络问题的诊断信号缺乏：
   - TiKV gRPC batch latency 飙升
   - Raft message duration 异常
   - TiDB client connection error rate 上升
   - 跨 AZ 延迟（若节点分布在多个 AZ）

## Fix Plan

### Step 1: 在 SKILL.md Node C 增加网络层诊断路径

```
延迟突升场景下，在分析 TopSQL/SlowQuery 之前，先评估 wait_time vs process_time：
- 若 wait_time >> process_time（wait_time > 5x process_time），优先检查网络/IO 层：
  1. TiKV gRPC 网络延迟：tikv_grpc_msg_duration_seconds P99
  2. Raft message 延迟：tikv_server_raft_message_duration P99
  3. TiDB→TiKV 请求批处理延迟
  4. Activity Hub 中是否有网络相关操作（VPC 变更、负载均衡器调整）
- 若 wait_time ≈ process_time，优先检查查询执行路径（TopSQL/执行计划）
```

### Step 2: 在 collect_evidence.py 中增加网络层指标采集

在 A2 段（metrics）补充网络相关 PromQL：

```python
# Network metrics
{
    "name": "tikv_grpc_latency_p99",
    "query": "histogram_quantile(0.99, rate(tikv_grpc_msg_duration_seconds_bucket[5m]))",
    "description": "TiKV gRPC request P99 latency"
},
{
    "name": "tikv_raft_message_latency_p99",
    "query": "histogram_quantile(0.99, rate(tikv_server_raft_message_duration_seconds_bucket[5m]))",
    "description": "TiKV Raft message P99 latency"
},
```

### Step 3: 在 Node D 增加根因鉴别规则

```
网络层 vs 查询层根因鉴别矩阵：
┌─────────────────────────────┬─────────────────────┬──────────────────────┐
│ 信号组合                     │ 倾向                 │ 主要根因              │
├─────────────────────────────┼─────────────────────┼──────────────────────┤
│ wait_time >> process_time    │ 网络/IO 等待         │ 检查 gRPC/IO 指标     │
│ gRPC P99 高 + CPU 正常       │ 网络层故障           │ 网络/AZ 问题          │
│ CPU 高 + process_time 高     │ 查询执行效率         │ 慢查询/索引/执行计划  │
│ wait_time ≈ process_time     │ 查询层               │ TopSQL/执行计划       │
└─────────────────────────────┴─────────────────────┴──────────────────────┘
```

## Verification

回归验证：选取一个已知网络层根因的 case，确认修复后 Agent 能正确输出：
1. wait_time vs process_time 比值分析
2. 网络层指标值
3. 正确的"网络问题"根因结论

## Related Issues

- ISS-0007: 热点节点下钻缺少决策规则（部分重叠）
- ISS-0068: 基础设施瓶颈 vs 查询问题推荐优先级（已修复 EBS IOPS 场景，未覆盖纯网络场景）
- ISS-0009: 跨数据源交叉验证缺失
- ISS-0086: PD TSO Wait Duration 诊断路径