Agent Skills
返回列表
💻

Python异常日志根因定位

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @user_2fd890c9/exception-logger。

技能介绍

线上报错看不懂,堆栈太长不想翻

生产环境的日志文件动辄几十 MB,异常 traceback 嵌在一堆无关的 INFO、DEBUG 日志中间。KeyError: 'uid' 到底是哪个模块抛出来的?这个 IndexError 是索引真的越界,还是上游数据缺字段导致的?手动 grep、逐帧读堆栈,一次定位可能要花十几分钟,遇到批量日志报错更是重复劳动。

这个技能做了什么

exception-logger 是一个纯静态的日志文本分析工具,不执行任何 Python 代码,不修改你的源文件。它从日志中提取四类关键信息:

  • 异常类型:识别 Python 内置异常,如 TypeError、ValueError、KeyError
  • 堆栈位置:解析 traceback 中的文件路径、行号、函数名,精确到 app.py:42 in process_data
  • 错误消息:提取异常的具体描述文本,例如 list index out of range
  • 根因分类:将异常映射到常见根因类别(类型错误、索引越界、键缺失等),并给出修复方向建议

核心工作流分三步:

  1. 准备包含完整 traceback 信息的日志文件,可用 grep -i "error\|exception" 预检
  2. 运行 exception-logger -i your.log,默认输出文本格式分析结果
  3. 排查 CI/CD 集成场景时使用 --format json 获得结构化输出,通过 jq 或脚本进一步消费

大文件场景下用 --stream 启用流式处理,默认按 64KB 块读取,内存占用稳定。

适用边界与注意点

能做的:仅支持 Python 内置异常类型的识别与规则映射;纯标准库实现,零第三方依赖,Python 3.8+ 即可运行;支持 --group-by type 对多日志做异常按类型分组统计。

不能做的:

  • 不识别自定义异常,需自行编辑 suggestion.py 补充映射规则
  • 不处理 Java、Go 等其他语言的日志格式
  • 不保证修复建议绝对正确——建议基于通用经验,需结合项目上下文判断
  • 不会自动改代码,输出的建议只是排查方向

工具内置了置信度门控机制:当日志缺少异常类型、行号等关键字段时,对应位置标记为 [需核实:file_path] 而非编造内容。异常类型不在内置规则表中时,提示 [需核实:suggestion],需要人工介入判断。

常见坑:只粘贴异常最后一行导致定位失败、一个日志文件混入多个异常类型、大日志直接全量加载内存导致溢出。建议保留完整 traceback 帧信息,超 100MB 的日志启用 --stream,CI 自动化流程统一用 JSON 输出。

使用场景

  • 线上 Python 服务频繁抛出 KeyError,需要从海量日志中定位出错文件和行号
  • CI/CD 流水线中测试失败,要自动解析失败日志的异常类型并生成结构化报告
  • 收到一份几十 MB 的 Python 服务日志,人工翻找其中的 traceback 非常耗时
  • 单元测试跑出一堆 TypeError,想批量提取异常分布和修复建议

适合人员

  • 线上服务出故障需要快速从 Python 日志中定位堆栈位置的后端工程师
  • 需要在 CI 流水线中自动分析失败测试日志的 DevOps 工程师
  • 负责 Python 微服务稳定性、要在告警后迅速定位异常根因的 SRE 人员
  • 正在排查 Python 脚本报错、希望理解 traceback 信息的初学者