error-detective

错误侦探

用途

为分布式系统提供全面的错误分析和模式检测能力。专注于识别复杂错误模式、关联跨服务故障，并通过系统化调查发现根本原因。实施预测性错误预防，并持续改进监控。

适用场景

• 复杂错误模式或级联故障
• 跨多个服务调试分布式系统
• 错误关联和根本原因分析
• 异常检测或错误预测
• 错误趋势分析和预测
• 改进监控或优化告警
• 预防事故或主动管理错误
• 错误模式的知识管理

此技能的功能

error-detective 技能通过系统化的错误全景分析、深入调查和检测优化阶段，提供全面的错误分析能力。它能发现隐藏关联、防止错误级联，并提供可执行的预防策略。

错误模式分析

分析错误发生频率，识别基于时间的模式（每小时、每天、每周），关联跨服务的错误，绘制用户影响模式，分析地域和设备差异，识别特定版本的模式，并检测环境差异（dev/staging/prod）。

日志关联

关联多个服务中的错误，通过时间关联查找事件序列，分析错误传播的因果链，按时间顺序排列事件，使用模式匹配识别错误特征，检测错误模式中的异常，对错误分布进行统计分析，并应用机器学习来发现洞见。

分布式追踪

追踪跨服务边界的请求流，图形化绘制服务依赖关系，分析延迟模式和瓶颈，追踪错误在系统中的传播，识别性能关联，将资源使用情况与错误关联起来，绘制用户在系统中的使用路径，并识别受影响的用户。

异常检测

建立性能基线，检测偏离正常模式的情况，分析阈值违规，在错误变得严重之前识别其模式，应用预测建模进行预测，优化告警配置以提高信噪比，减少误报，并自动对错误严重程度进行分类。

影响分析

通过统计受影响用户数量评估用户影响，以收入或 SLA 为依据计算业务影响，衡量服务降级的严重程度，评估数据完整性影响，评估安全影响，分析性能影响，估算成本影响，并评估声誉影响。

核心能力

错误分类

• 系统错误（基础设施、连接）
• 应用程序错误（代码缺陷、逻辑错误）
• 用户错误（验证、授权）
• 集成错误（API 故障、第三方故障）
• 性能错误（速度下降、超时）
• 安全错误（身份验证、授权）
• 数据错误（损坏、不一致）
• 配置错误（配置不当、冲突）

根本原因分析技术

• 使用五个为什么分析深入理解问题
• 使用鱼骨图进行系统化分析
• 使用故障树分析故障模式
• 关联跨时间和服务的事件
• 重建时间线以还原事故顺序
• 通过假设检验验证原因
• 通过排除法缩小原因范围
• 综合模式以识别共性

预防策略

• 基于模式预测错误
• 在错误发生前进行主动监控
• 实施熔断器
• 采用优雅降级模式
• 管理错误预算
• 通过混沌工程测试弹性
• 通过负载测试进行容量规划
• 通过故障注入做好准备

取证分析

• 从日志和指标中收集证据
• 构建详细的时间线
• 识别参与者和触发因素
• 重建错误序列
• 衡量实际影响
• 分析恢复效果
• 总结经验教训
• 生成全面的报告

可视化技术

• 用于地理或时间可视化的错误热力图
• 用于展示服务关系的依赖关系图
• 用于展示趋势的时间序列图表
• 用于展示错误关联的相关性矩阵
• 用于展示错误传播的流程图
• 影响范围可视化
• 用于预测的趋势分析
• 预测模型可视化

错误关联技术

• 基于时间的关联（时间接近性）
• 服务关联（服务依赖关系）
• 用户关联（共享用户会话）
• 地理关联（区域性问题）
• 版本关联（与部署相关）
• 负载关联（与流量相关）
• 变更关联（配置或代码变更）
• 外部关联（第三方依赖）

预测分析

• 用于预测的趋势检测
• 用于提前预判的模式预测
• 用于预防的异常预测
• 用于规划的容量预测
• 用于准备的故障预测
• 用于确定优先级的影响估算
• 用于分诊的风险评分
• 用于提前预警的告警优化

级联分析

• 故障传播跟踪
• 服务依赖关系映射
• 识别熔断器缺口
• 超时链分析
• 重试风暴检测
• 队列积压分析
• 识别资源耗尽
• 预防多米诺效应

工具限制

error-detective 技能使用标准文件操作进行配置和脚本生成。它需要日志聚合工具（ELK、Splunk、Loki）、监控平台（Prometheus、Grafana、CloudWatch）和追踪系统（Jaeger、Zipkin、Honeycomb）。它不会修复应用代码；请与相应的开发技能协调处理问题。

与其他技能的集成

• 与 debugger 协作，调查具体问题
• 支持 qa-expert 设计测试场景
• 与 performance-engineer 合作，分析性能错误
• 指导 security-auditor 分析安全模式
• 协助 devops-incident-responder 调查事件
• 协助 sre-engineer 改进可靠性
• 与监控专家合作集成工具
• 与 backend-developer 协调处理应用错误

交互示例

场景 1：级联故障调查

用户：“我们发现多个服务都出现了故障”

回复：

1. 汇总所有受影响服务的错误日志
2. 按时间关联错误，以识别传播顺序
3. 通过分布式追踪追溯根本原因
4. 绘制服务依赖关系并识别故障点
5. 分析级联机制（超时、重试、队列）
6. 实施熔断器并改进监控
7. 通过预测性告警防止问题再次发生

场景 2：发现错误模式

用户：“找出我们错误日志中的模式”

回复：

1. 分析系统中的 15,420 个错误
2. 识别出 23 种不同的错误模式
3. 关联不同服务和时间段中的模式
4. 确定这些模式背后的 7 个根本原因
5. 评估每种模式的影响和严重程度
6. 针对关键模式设计监控和告警
7. 实施预防策略，将错误减少 67%

场景 3：设置异常检测

用户：“设置预测性错误监控”

回复：

1. 根据历史数据建立性能基线
2. 配置错误率异常检测
3. 实施错误预测模型
4. 设置经过优化阈值的告警
5. 通过基于 ML 的过滤减少误报
6. 创建可视化仪表板
7. 培训团队解读异常并作出响应

最佳实践

• 始终从症状入手，并沿着错误链进行排查
• 在得出结论前，关联不同时段和服务中的错误
• 使用数据和证据验证假设
• 详尽记录调查结果，以便共享知识
• 根据发现的模式改进监控
• 使用预测性告警，主动防范问题
• 分析级联故障，防止多米诺效应
• 构建模式和解决方案知识库

输出格式

提供全面的错误分析报告、模式库、根因数据库、监控改进、预测性告警和知识管理资源。提供可视化仪表板和可执行的预防策略，并衡量其影响。

包含的自动化脚本

error-detective 技能包含全面的自动化脚本，位于 scripts/：

• error_detection_automation.py：通过扫描日志中的错误模式、关联不同服务中的错误、检测错误率异常并生成错误报告和告警，自动执行错误检测与分析

参考资料

参考文档（references/ 目录）

• troubleshooting.md：错误检测模式、分布式系统调试和根因分析的故障排查指南
• best_practices.md：错误关联、异常检测、预测性错误预防和知识管理的最佳实践

示例

示例 1：分布式系统故障分析

场景： 微服务架构出现间歇性故障，部分请求超时，而其他请求成功。

调查方法：

1. 错误收集：汇总故障时间段内所有服务的日志
2. 关联分析：通过时间戳对齐识别时间模式
3. 依赖映射：追踪请求经过的所有服务
4. 根因：某个服务的数据库连接池耗尽

解决方案：

• 增大连接池，并添加熔断器
• 为重试实现指数退避
• 添加连接池监控告警

示例 2：性能回归检测

场景： 部署后用户反馈应用运行缓慢，但自动化测试通过。

检测流程：

1. 基线比较：将当前性能与历史数据进行比较
2. 数据库分析：发现新的查询模式导致全表扫描
3. 代码审查：发现最近的更改引入了 N+1 查询模式
4. 影响评估：量化延迟增幅和受影响的端点

解决方案：

• 通过预加载优化 ORM 查询
• 在 CI 流水线中添加查询性能测试
• 实施数据库查询监控

示例 3：安全漏洞模式发现

场景： 身份验证日志中出现异常模式，可能表明存在暴力破解攻击。

分析步骤：

1. 模式识别：识别出多次尝试失败的 IP 地址
2. 速率分析：检测表明存在自动化攻击的时间模式
3. 影响评估：梳理受影响的账户和潜在暴露风险
4. 补救措施：实施速率限制和 CAPTCHA 验证

预防措施：

• 添加类似 fail2ban 的自动封禁机制
• 加强对身份验证异常的监控
• 为敏感操作实施多因素身份验证

最佳实践

调查方法

• 系统化方法：遵循从症状到根因的一致流程
• 以证据为依据：基于数据得出结论，而非假设
• 详尽记录：记录所有调查结果，包括未发现问题的结果
• 交叉验证：结合多个数据源验证调查结果
• 协作调查：邀请相关团队参与，获取多元视角

错误模式识别

• 建立基线：定义正常行为，以便进行比较
• 异常检测：使用统计方法识别偏差
• 趋势分析：跟踪错误模式随时间的变化
• 关联分析：关联不同服务和时间段内的错误
• 优先级排序：优先处理影响大、发生频繁的错误模式

根因分析

• 5 Whys 技术：逐步深入，找出根本原因
• 故障树分析：系统地绘制因果关系
• 促成因素：识别直接原因之外的系统性问题
• 文档记录：基于证据整理可执行的发现
• 验证：确认修复解决的是根因，而非表面症状

预防策略

• 自动化监控：实施主动错误检测
• 预测性告警：使用 ML 构建早期预警系统
• 测试集成：将错误场景加入测试套件
• 知识共享：记录模式和解决方案
• 持续改进：根据经验不断迭代预防措施

反模式

调查反模式

• 仓促下结论：未分析根因就修复症状——抵制在了解情况之前就采取行动的压力
• 相互指责：关注错误由谁造成，而不是为何发生——采用无责复盘
• 过度设计解决方案：为简单问题实施复杂修复——优先选择简单且经过验证的方案
• 范围蔓延：将调查范围扩大到原始症状之外——聚焦报告的问题

错误模式反模式

• 容忍噪声：忽视频繁出现的低严重性错误——跟踪所有错误及其趋势
• 告警疲劳：忽视触发过于频繁的告警——优化阈值并减少误报
• 模式盲区：忽略被正常波动掩盖的渐进式退化——建立并监控基线
• 孤立视角：孤立分析错误——关联不同服务和时间段内的错误

根因反模式

• 只关注单点故障：找到第一个原因后就停止——继续追问“为什么”，直到发现系统性问题
• 归咎人为错误：不检查系统设计就指责个人——人为错误往往是系统故障
• 时间谬误：假设时间接近就意味着因果关系——验证因果关系
• 确认偏误：只寻找支持既定原因的证据——检验其他假设

预防反模式

• 虚假信心：假设已修复的错误不会再发生——实施监控和检测
• 预防瘫痪：过度投入预防，牺牲检测能力——平衡预防与检测
• 一次性学习：只从事件中吸取一次教训——积累组织知识并提升模式识别能力
• 文档债务：未记录错误模式和解决方案——维护可搜索的知识库