Root Cause Tracing

Root Cause Tracing

hongmaple0820 a153e08 4.8 KB Updated Sep 17, 2026

Coding & Dev Tools

Install

Press C to copy

$ npx skillmds@latest add hongmaple0820/root-cause-tracing

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

Download SKILL.md

＋ Add to collection

README badge

[![SkillMD](https://skillmd.com/badge/hongmaple0820/root-cause-tracing.svg)](https://skillmd.com/skills/hongmaple0820/root-cause-tracing)

Trust & safety

Audits pending

Not yet audited · commit a153e08

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

Root Cause Tracing

追踪错误的根本原因，找到问题的真正源头。

激活场景

遇到复杂的错误或 bug
错误信息不够清晰
需要从错误点回溯到源头
用户说"找原因"、"为什么出错"、"根因分析"

核心思想

错误的表现往往不是真正的原因。需要逐层回溯，找到触发问题的根源。

症状 → 直接原因 → 间接原因 → 根本原因

分析流程

1. 收集信息

# 查看完整错误堆栈
cat error.log | tail -100

# 查看相关日志
grep -B 10 -A 5 "ERROR" app.log

# 查看系统状态
dmesg | tail -50

记录以下信息：

错误消息
完整堆栈跟踪
发生时间
触发条件
环境信息

2. 5 Whys 分析法

连续问 5 次"为什么"，直到找到根本原因。

示例：

问题：用户无法登录

为什么？ → 服务器返回 500 错误
为什么？ → 数据库查询失败
为什么？ → 数据库连接超时
为什么？ → 连接池耗尽
为什么？ → 有代码没有正确释放连接 ← 根本原因

3. 堆栈追踪

从错误点开始，逐层向上追踪：

Error: Connection timeout
    at Database.query (db.js:45)        ← 直接错误点
    at UserService.findById (user.js:23) ← 调用者
    at AuthController.login (auth.js:67) ← 更上层
    at Router.handle (router.js:89)      ← 路由层

检查每一层：

输入是什么？
预期行为是什么？
实际发生了什么？

4. 时间线分析

10:00:00 - 系统正常
10:05:00 - 部署了新版本
10:10:00 - 开始出现错误
10:15:00 - 错误数量激增

关键问题：

什么变化发生在错误之前？
是逐渐恶化还是突然发生？
是否有周期性？

5. 隔离测试

# 测试单个组件
curl http://localhost:3000/health

# 测试数据库连接
mysql -h localhost -u root -p -e "SELECT 1"

# 测试网络
ping api.example.com
curl -I https://api.example.com

逐个排除可能的原因。

常见根因类别

代码问题

类型	特征	解决方向
空指针	`Cannot read property of undefined`	添加空值检查
类型错误	`TypeError`	验证输入类型
竞态条件	偶发性失败	添加锁/同步机制
内存泄漏	随时间恶化	检查资源释放
死锁	卡住不动	检查锁的顺序

配置问题

类型	特征	解决方向
环境变量缺失	启动时失败	检查 .env 文件
权限不足	Permission denied	检查文件/目录权限
端口冲突	Address in use	检查端口占用
路径错误	File not found	检查相对/绝对路径

外部依赖

类型	特征	解决方向
API 变更	字段缺失	检查 API 文档
服务不可用	Connection refused	检查服务状态
超时	Timeout	增加超时时间或重试
限流	429 Too Many Requests	添加限流/重试逻辑

调试工具

日志分析

# 按时间过滤
grep "2024-02-06 10:" app.log

# 统计错误类型
grep "ERROR" app.log | cut -d':' -f4 | sort | uniq -c | sort -rn

# 追踪请求
grep "request-id-123" app.log

性能分析

# 查看进程状态
top -p $(pgrep node)

# 查看打开的文件
lsof -p $(pgrep node) | wc -l

# 查看网络连接
netstat -an | grep ESTABLISHED | wc -l

数据库分析

-- 查看慢查询
SHOW PROCESSLIST;

-- 查看锁
SHOW ENGINE INNODB STATUS;

-- 查看连接数
SHOW STATUS LIKE 'Threads_connected';

输出格式

根因分析报告

# 根因分析报告

## 问题描述
用户登录时返回 500 错误

## 时间线
- 10:05 - 部署版本 v1.2.3
- 10:10 - 首次出现错误
- 10:20 - 错误率达到 30%
- 10:30 - 回滚到 v1.2.2
- 10:35 - 错误消失

## 根本原因
新版本中修改了数据库查询，缺少对空结果的处理，
导致后续代码尝试访问 undefined 的属性。

## 直接原因
`user.profile.name` 访问失败，因为 `user.profile` 为 null

## 触发条件
- 新注册用户尚未设置 profile
- 占用户总数约 5%

## 解决方案
1. 添加空值检查：`user.profile?.name`
2. 添加单元测试覆盖此场景
3. 添加数据迁移脚本初始化空 profile

## 预防措施
- 代码审查时检查空值处理
- 添加更多边界条件测试
- 灰度发布降低影响范围

思维模式

假设-验证：提出假设，设计实验验证
二分法：缩小问题范围，定位问题区域
对比法：对比正常和异常情况的差异
最小复现：找到能复现问题的最小条件
反向推理：从结果倒推可能的原因

---name: root-cause-tracingdescription: Root Cause Tracing---# Root Cause Tracing追踪错误的根本原因，找到问题的真正源头。## 激活场景- 遇到复杂的错误或 bug- 错误信息不够清晰- 需要从错误点回溯到源头- 用户说"找原因"、"为什么出错"、"根因分析"## 核心思想错误的表现往往不是真正的原因。需要逐层回溯，找到触发问题的根源。```症状 → 直接原因 → 间接原因 → 根本原因```## 分析流程### 1. 收集信息```bash# 查看完整错误堆栈cat error.log | tail -100# 查看相关日志grep -B 10 -A 5 "ERROR" app.log# 查看系统状态dmesg | tail -50```记录以下信息：- 错误消息- 完整堆栈跟踪- 发生时间- 触发条件- 环境信息### 2. 5 Whys 分析法连续问 5 次"为什么"，直到找到根本原因。**示例**：**问题**：用户无法登录1. **为什么？** → 服务器返回 500 错误2. **为什么？** → 数据库查询失败3. **为什么？** → 数据库连接超时4. **为什么？** → 连接池耗尽5. **为什么？** → 有代码没有正确释放连接 ← **根本原因**### 3. 堆栈追踪从错误点开始，逐层向上追踪：```Error: Connection timeout at Database.query (db.js:45) ← 直接错误点 at UserService.findById (user.js:23) ← 调用者 at AuthController.login (auth.js:67) ← 更上层 at Router.handle (router.js:89) ← 路由层```检查每一层：- 输入是什么？- 预期行为是什么？- 实际发生了什么？### 4. 时间线分析```10:00:00 - 系统正常10:05:00 - 部署了新版本10:10:00 - 开始出现错误10:15:00 - 错误数量激增```关键问题：- 什么变化发生在错误之前？- 是逐渐恶化还是突然发生？- 是否有周期性？### 5. 隔离测试```bash# 测试单个组件curl http://localhost:3000/health# 测试数据库连接mysql -h localhost -u root -p -e "SELECT 1"# 测试网络ping api.example.comcurl -I https://api.example.com```逐个排除可能的原因。## 常见根因类别### 代码问题| 类型 | 特征 | 解决方向 ||------|------|----------|| 空指针 | `Cannot read property of undefined` | 添加空值检查 || 类型错误 | `TypeError` | 验证输入类型 || 竞态条件 | 偶发性失败 | 添加锁/同步机制 || 内存泄漏 | 随时间恶化 | 检查资源释放 || 死锁 | 卡住不动 | 检查锁的顺序 |### 配置问题| 类型 | 特征 | 解决方向 ||------|------|----------|| 环境变量缺失 | 启动时失败 | 检查 .env 文件 || 权限不足 | Permission denied | 检查文件/目录权限 || 端口冲突 | Address in use | 检查端口占用 || 路径错误 | File not found | 检查相对/绝对路径 |### 外部依赖| 类型 | 特征 | 解决方向 ||------|------|----------|| API 变更 | 字段缺失 | 检查 API 文档 || 服务不可用 | Connection refused | 检查服务状态 || 超时 | Timeout | 增加超时时间或重试 || 限流 | 429 Too Many Requests | 添加限流/重试逻辑 |## 调试工具### 日志分析```bash# 按时间过滤grep "2024-02-06 10:" app.log# 统计错误类型grep "ERROR" app.log | cut -d':' -f4 | sort | uniq -c | sort -rn# 追踪请求grep "request-id-123" app.log```### 性能分析```bash# 查看进程状态top -p $(pgrep node)# 查看打开的文件lsof -p $(pgrep node) | wc -l# 查看网络连接netstat -an | grep ESTABLISHED | wc -l```### 数据库分析```sql-- 查看慢查询SHOW PROCESSLIST;-- 查看锁SHOW ENGINE INNODB STATUS;-- 查看连接数SHOW STATUS LIKE 'Threads_connected';```## 输出格式### 根因分析报告```markdown# 根因分析报告## 问题描述用户登录时返回 500 错误## 时间线- 10:05 - 部署版本 v1.2.3- 10:10 - 首次出现错误- 10:20 - 错误率达到 30%- 10:30 - 回滚到 v1.2.2- 10:35 - 错误消失## 根本原因新版本中修改了数据库查询，缺少对空结果的处理，导致后续代码尝试访问 undefined 的属性。## 直接原因`user.profile.name` 访问失败，因为 `user.profile` 为 null## 触发条件- 新注册用户尚未设置 profile- 占用户总数约 5%## 解决方案1. 添加空值检查：`user.profile?.name`2. 添加单元测试覆盖此场景3. 添加数据迁移脚本初始化空 profile## 预防措施- 代码审查时检查空值处理- 添加更多边界条件测试- 灰度发布降低影响范围```## 思维模式1. **假设-验证**：提出假设，设计实验验证2. **二分法**：缩小问题范围，定位问题区域3. **对比法**：对比正常和异常情况的差异4. **最小复现**：找到能复现问题的最小条件5. **反向推理**：从结果倒推可能的原因

hongmaple0820/agent-academy/tree/main/skills/development/root-cause-tracing commit a153e08fd0

Frequently asked questions

npx skillmds@latest add hongmaple0820/root-cause-tracing