open-rca-diagnosis

name	open_rca_diagnosis
description	AI驱动的微服务故障根因分析技能，通过系统化的遥测数据分析流程，精准定位故障根本原因
type	analysis
author	derisk
version	1.0
category	observability
tags	["rca","fault-diagnosis","observability","sre","microservices"]
parameters	{"scene":{"type":"string","description":"场景标识，用于加载对应的场景规格文档","required":true,"enum":["bank","telecom","market"],"default":"bank"},"question":{"type":"string","description":"故障问题描述，包含故障现象、时间范围等关键信息","required":true}}

故障根因分析技能 (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 也可能有价值
后置阈值	禁止在过滤时间段后计算阈值

数据分析规范

阈值计算规范

# 正确做法：使用完整数据计算全局阈值
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)  # 错误！

时间处理规范

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	初始版本，支持标准化故障诊断流程