52 lines
2.3 KiB
Markdown
52 lines
2.3 KiB
Markdown
---
|
||
name: root-cause-tracing
|
||
description: Root cause analysis (RCA) and tracing failures back to the original trigger across call stacks and data flows. Triggers: root cause, RCA, trace, why, 根因, 溯源, 复盘, 定位根因.
|
||
---
|
||
|
||
# Root Cause Tracing（根因溯源 / RCA）
|
||
|
||
## When to Use
|
||
- 错误发生在深层栈/异步链路/多模块交互处，症状离根因很远
|
||
- 需要写清楚“为什么会这样”以及“如何防止再发生”
|
||
|
||
## Inputs（required）
|
||
- Symptom：错误现象 + 触发条件（脱敏后的日志/堆栈/截图）
|
||
- Repro：复现步骤（或说明目前无法稳定复现）
|
||
- Context：关键业务不变量/约束（例如权限边界、数据一致性要求）
|
||
- Timeline：最近变更范围（commit/PR/发布时间点，若可提供）
|
||
|
||
## Procedure
|
||
1. **Anchor the Symptom**
|
||
- 把“现象”翻译成可验证的断言（expected vs actual）
|
||
- 明确影响面：用户/数据/安全/性能/成本
|
||
|
||
2. **Trace the Path**
|
||
- 从症状点沿着：调用栈 → 异步链路 → 事件/消息 → 数据读写路径回溯
|
||
- 标注每一跳的关键输入/输出（哪些值第一次变“坏”）
|
||
|
||
3. **Find the First Divergence**
|
||
- 找到“最早的错误状态/错误输入/错误决策点”
|
||
- 用对照实验证明：没有这个条件就不会出现症状
|
||
|
||
4. **Prove the Root Cause**
|
||
- 用证据闭环：日志/trace/断言/最小复现/二分定位（如 `git bisect`）
|
||
- 区分：
|
||
- **Root cause**：触发源（必须修）
|
||
- **Contributing factors**：放大器/缺失的 guardrail（建议补）
|
||
|
||
5. **Fix at the Root + Add Guardrails**
|
||
- 在触发源处修复（输入校验/状态机/边界条件/并发控制）
|
||
- 增加防线：断言、错误处理、熔断/限流、幂等、测试用例
|
||
|
||
## Output Contract（RCA 模板）
|
||
- Impact：影响范围（用户/数据/安全/性能）+ 严重级别
|
||
- Trigger：触发条件（最小化）
|
||
- Root Cause：根因（定位到模块/函数/配置/依赖）
|
||
- Evidence：证据链（复现、日志片段、对照实验、定位方法）
|
||
- Fix：修复摘要（为什么这样修、是否兼容、回滚策略）
|
||
- Prevention：预防措施（测试、监控、校验、文档、流程）
|
||
|
||
## Guardrails
|
||
- 只写“可证伪”的根因，不写形容词结论
|
||
- 无复现时：先补可观测性与缩小范围，再讨论修复
|