# ISS-0089: vmstorage sample limit exceeded — 大集群 P99 延迟指标查询静默失败

## Background

TCID-12704（cluster 10123293495242577103，GCP asia-northeast1，2026-05-13）postmortem 中，
collect_evidence.py 在查询 TiDB P99 latency 指标时返回：

```
error: err: sample limit exceeded, rsp.SeriesCount: 34, maxSeries: 30000
```

错误来自 vmstorage 后端。对于 34 节点的大集群，按实例维度查询 P99 latency
返回的时间序列数量（每节点×每时间点）超过了 vmstorage 默认的 30000 样本上限。

collect_evidence.py 的 A1/A2 段将此错误记录在 evidence_summary 的 errors 字段，
但诊断输出中没有向用户明确说明"TiDB P99 延迟数据不可用"，导致诊断报告中
缺少该关键性能指标的状态说明。

## Observed Error (from TCID-12704 workspace ws-1779156165000-34f5ef8b3)

```
Tool: collect_evidence.py metrics query
Error: "error: err: sample limit exceeded, rsp.SeriesCount: 34, maxSeries: 30000"
Affected metric: tidb_query_duration_seconds (P99 by instance)
Cluster size: 34 TiDB nodes
```

Agent 在诊断 A1 段通过了 evidence_summary errors，但最终输出中未出现任何
关于 P99 latency 不可用的声明。用户/reviewer 无法区分"P99 数据存在但正常"
与"P99 数据查询失败"两种情况。

## Root Cause Analysis

1. **vmstorage sample limit**: 默认上限 ~30000 samples/query，对大集群
   （34 TiDB 节点 × 5min 窗口的时间点）可能超出。
2. **collect_evidence.py 错误处理**: 当 Clinic API 返回包含 "sample limit" 的错误时，
   脚本记录了错误但未采取任何降级策略（加大 step / 缩小时间范围）。
3. **evidence_summary 中 errors 字段未被诊断输出消费**: Agent 读取
   evidence_summary_for_agent.txt 后，诊断流程中没有强制要求检查 errors 字段
   并在输出中报告数据可用性。

## Fix Plan

### 方案 A（推荐）：collect_evidence.py 加 step 自适应重试

1. 在 collect_evidence.py 的指标查询逻辑中，检测 "sample limit exceeded" 错误
2. 自动以 2x step 间隔重试（例如 30s → 60s → 120s），最多 3 次
3. 若所有重试均失败，在 evidence_summary 的对应 metric 条目中写入
   `"availability": "failed"` 和具体错误信息
4. 在 evidence_summary_for_agent.txt 中明确列出不可用指标

```python
# collect_evidence.py 伪代码
def query_with_fallback(cluster_id, query, start, end, step=30):
    for multiplier in [1, 2, 4]:
        result = clinic_cli_metrics(cluster_id, query, start, end, step * multiplier)
        if "sample limit exceeded" not in result.get("error", ""):
            return result
    return {"error": f"sample limit exceeded after retries", "availability": "failed"}
```

### 方案 B：SKILL.md 补充诊断前置检查

在 SKILL.md Node C 增加：
> 读取 evidence_summary 的 errors 字段。若有指标查询失败（尤其是 P99 latency），
> 在诊断输出中明确标注"[数据不可用] {metric} 查询失败: {error}"，
> 并解释对诊断置信度的影响。

## Verification

修复后验证：
1. 对 TCID-12704 重跑 collect_evidence.py，确认 P99 latency 能以更大 step 成功查询
2. 验证 evidence_summary 中 errors 字段被诊断输出正确引用
3. 对小集群（≤8 节点）确认正常 step=30s 查询不受影响