Python异常日志根因定位
将以下提示词粘贴到你的 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 - 根因分类:将异常映射到常见根因类别(类型错误、索引越界、键缺失等),并给出修复方向建议
核心工作流分三步:
- 准备包含完整 traceback 信息的日志文件,可用
grep -i "error\|exception"预检 - 运行
exception-logger -i your.log,默认输出文本格式分析结果 - 排查 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 信息的初学者