# Open Rca Diagnosis

> 故障问题描述，包含故障现象、时间范围等关键信息 Use when this capability is needed.

- Skill: `tomevault-io/open-rca-diagnosis` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/open-rca-diagnosis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/open-rca-diagnosis/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/open-rca-diagnosis

---


# 故障根因分析技能 (Open RCA Diagnosis)

## 技能概述

本技能是一个系统化的故障根因诊断框架，通过分析微服务系统的遥测数据（指标、链路追踪、日志），遵循科学的方法论定位故障根本原因。

## 分析方法论

本技能基于以下核心分析方法论：

1. **数据驱动** - 所有诊断结论必须有遥测数据支撑
2. **层次化分析** - 从业务层到基础设施层逐层下钻
3. **阈值判定** - 基于统计阈值识别异常
4. **因果链追踪** - 通过调用链路追踪故障传播路径
5. **交叉验证** - 多维度数据交叉验证根因

## 诊断工作流程

### Phase 1: 数据预处理 (Preprocessing)

**目标**：建立分析基础，了解数据全貌

#### 步骤 1.1：数据探索
- 探测遥测数据目录结构
- 识别可用的数据类型（metric/trace/log）
- 确定数据时间范围和文件列表

#### 步骤 1.2：组件识别
- 提取所有组件标识（cmdb_id）
- 按层级分类组件
- 映射组件与服务的对应关系

#### 步骤 1.3：阈值计算
- **关键原则**：必须使用完整历史数据计算全局阈值
- 聚合每个组件的每个 KPI 形成时间序列
- 计算全局百分位阈值（P95/P90/P75/P50/P25/P10/P5）
- **禁止**使用过滤后的数据计算阈值

#### 步骤 1.4：时间窗口过滤
- 根据问题描述确定故障时间范围
- 将时间戳转换为统一格式
- 过滤出故障时间窗口内的数据

### Phase 2: 异常检测

**目标**：识别偏离正常范围的异常数据点

#### 步骤 2.1：业务指标异常
- 检查 `rr`（请求成功率）异常下降
- 检查 `sr`（服务成功率）异常下降
- 检查 `mrt`（平均响应时间）异常上升
- **注意**：业务指标下降可能低于阈值而非高于

#### 步骤 2.2：资源指标异常
- CPU 使用率异常（高于 P95）
- 内存使用率异常（高于 P95）
- 网络 I/O 异常
- 磁盘 I/O 异常

#### 步骤 2.3：阈值调整策略
- 若无异常发现，逐步放宽阈值
- 调整顺序：P95 → P90 → P75
- 对于下降型指标：P95 → P15 → P5

### Phase 3: 故障识别

**目标**：将离散异常点聚合为连续故障事件

#### 步骤 3.1：连续异常检测
- 将时间连续的异常数据点聚合成故障子序列
- 记录故障开始时间、结束时间、持续时间

#### 步骤 3.2：噪声过滤
- 过滤孤立的尖峰（单点异常）
- 计算阈值突破幅度（极值偏离阈值百分比）
- 排除突破幅度过小的误报（< 50%）

#### 步骤 3.3：故障组件标注
- 标注每个故障涉及的组件
- 标注每个故障涉及的资源 KPI
- 记录故障的严重程度

### Phase 4: 根因定位

**目标**：从多个故障事件中确定根本原因

#### 步骤 4.1：故障层级判定

**场景 A：不同层级存在故障**
- 比较各层级故障的阈值突破幅度
- 突破幅度最大的层级为根因层级（需 >> 50%）
- 此规则仅用于确定层级，不用于确定具体组件

**场景 B：同层级多个故障组件**
- 使用链路追踪分析调用链
- 识别调用链中最下游的故障组件
- 最下游故障组件为根因候选

**场景 C：单组件单 KPI 故障**
- 该故障即为根因
- 结合日志确认具体原因

#### 步骤 4.2：链路追踪分析

**调用链解析规则**：
- 构建 trace 的父子调用关系树
- 从根节点向叶节点遍历
- 识别调用链中的故障节点

**根因判定规则**：
- 根因 = 调用链中最下游的【故障】组件
- 注意：最下游不一定是根因，必须先是故障组件
- 健康组件在故障下游不作为根因

#### 步骤 4.3：日志分析

**日志分析要点**：
- 不仅关注 ERROR/WARNING 日志
- INFO 日志可能包含关键操作信息
- 寻找与故障时间点匹配的日志
- 提取错误详情和堆栈信息

**日志关联规则**：
- 时间戳关联：日志时间与故障时间匹配
- 组件关联：日志来源与故障组件匹配
- 内容关联：日志内容与故障类型相关

## 关键规则

### 必须遵守

| 规则 | 说明 |
|------|------|
| 全局阈值计算 | 使用完整历史数据计算阈值，禁止使用过滤后数据 |
| 时区统一 | 所有时间处理使用 UTC+8 时区 |
| 指标优先 | 首先使用指标缩小搜索范围，再分析 trace 和 log |
| 链路定向 | 同层级多故障使用链路追踪定位最下游故障组件 |
| 交叉验证 | 使用 trace 和 log 交叉验证根因推断 |
| 数据溯源 | 所有结论必须有数据支撑，禁止臆测 |

### 禁止事项

| 禁止项 | 原因 |
|--------|------|
| 可视化绘图 | 环境不支持 matplotlib/seaborn，只能文本输出 |
| 本地存储 | 禁止将数据写入本地文件系统 |
| 假设数据 | 不假设任何未知变量或数据存在 |
| 误判健康 | 不将健康组件错误识别为根因 |
| 忽略信息日志 | 日志分析时不仅看 ERROR，INFO 也可能有价值 |
| 后置阈值 | 禁止在过滤时间段后计算阈值 |

## 数据分析规范

### 阈值计算规范

```python
# 正确做法：使用完整数据计算全局阈值
df_full = pd.read_csv('metric_container.csv')
threshold = df_full['value'].quantile(0.95)

# 错误做法：使用过滤后数据计算阈值
df_filtered = df_full[df_full['timestamp'] >= start_time]
threshold = df_filtered['value'].quantile(0.95)  # 错误！
```

### 时间处理规范

```python
import pytz
from datetime import datetime

# 统一使用 UTC+8 时区
tz = pytz.timezone('Asia/Shanghai')

# 秒级时间戳转换
dt = datetime.fromtimestamp(timestamp_seconds, tz=tz)

# 毫秒级时间戳转换
dt = datetime.fromtimestamp(timestamp_ms / 1000, tz=tz)
```

### 组件标识处理

不同场景的组件标识格式不同，需根据场景规格文档解析：
- Bank 场景：`Tomcat01`, `Mysql01`
- Telecom 场景：`os_001`, `docker_001`, `db_001`
- Market 场景：`node-1.adservice-0`, `adservice-grpc`

## 输出规范

### 诊断报告结构

1. **根因定位信息**
   - 故障发生时间
   - 根因组件
   - 根本原因

2. **分析思路流程图**
   - 使用 flow-diagram 展示推理过程

3. **证据链**
   - 指标异常证据
   - 链路追踪证据
   - 日志分析证据

### 图表输出格式

支持以下图表类型（使用 vis-chart 标签）：
- 折线图：时序数据展示
- 柱形图：分类数据对比
- 饼图：比例数据展示
- 流程图：诊断步骤展示

## 场景规格引用

本技能通过 `scene` 参数动态加载对应场景的规格文档：

```
specs/
├── bank_spec.md      # 银行场景规格
├── telecom_spec.md   # 电信场景规格
└── market_spec.md    # 电商场景规格
```

场景规格文档包含：
- 数据目录结构
- 数据模式定义（字段说明、示例数据）
- 候选根因组件列表
- 候选根因原因列表
- 时间戳单位约定
- cmdb_id 格式约定
- 系统特点说明

## 使用示例

```
输入参数:
  scene: bank
  question: "2021-03-05 02:00 到 03:00 期间，系统成功率下降到 50% 以下，请分析根因"

诊断流程:
1. 加载 bank_spec.md 获取场景规格
2. 探索数据目录，识别可用数据
3. 计算各 KPI 全局阈值
4. 过滤故障时间窗口数据
5. 检测异常组件和 KPI
6. 分析链路追踪定位根因
7. 交叉验证日志信息
8. 生成诊断报告
```

## 版本历史

| 版本 | 日期 | 更新内容 |
|------|------|----------|
| 1.0 | 2024-01 | 初始版本，支持标准化故障诊断流程 |

---
> Source: [derisk-ai/OpenDerisk](https://github.com/derisk-ai/OpenDerisk) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-23 -->