Python异常日志记录与错误排查技巧

Python异常日志记录远不止于“打印错误”，其核心价值在于赋能高效、精准的故障排查：通过完整traceback、脱敏后的业务上下文（如用户ID、订单号、trace_id）、科学的日志分级（ERROR/WARNING/INFO/DEBUG）以及结构化JSON输出，让每一条日志都成为可检索、可关联、可追溯的问题线索；掌握logging.exception()替代print、统一注入请求上下文、敏感信息自动过滤、全链路trace_id透传等实战技巧，能显著降低日志噪音、提升定位速度，真正实现“看一眼日志，就知道问题在哪、为何发生、如何复现”。

Python异常日志记录不是简单地把错误打出来，关键在于让日志能帮你快速定位问题：在哪一行、什么上下文、变量值是什么、是否重复发生。

用 logging.exception() 代替 print(e)

直接 print 异常信息只显示错误类型和消息，丢失完整的调用栈（traceback），也无法区分日志级别。logging.exception() 会自动记录完整 traceback，并默认以 ERROR 级别写入日志。

• ✅ 正确写法：logging.error("处理用户请求失败", exc_info=True) 或更简洁的 logging.exception("处理用户请求失败")
• ❌ 避免写法：print(e)、logging.error(str(e))（无堆栈）、logging.error(traceback.format_exc())（冗余且不易控制格式）

在关键位置加上下文信息

光有 traceback 不够，比如“KeyError: 'user_id'”无法判断是哪个请求、哪个用户、什么参数导致的。应在日志中显式带上可识别的业务上下文。

• 记录请求 ID、用户 ID、关键输入参数（脱敏后）：logging.exception("订单创建失败", extra={"order_id": order_id, "user_id": user.id, "amount": amount})
• 使用 LoggerAdapter 或自定义 filter 统一注入 request_id 等全局上下文，避免每个 log 调用都手动传 extra
• 对敏感字段如密码、token，务必先过滤或打码，再写入日志

按场景分级记录，不全堆 ERROR

不是所有异常都要记为 ERROR。合理使用 WARNING、INFO 甚至 DEBUG，能大幅降低日志噪音，提升排查效率。

• 预期可能发生的异常（如第三方 API 限流返回 429）→ 记为 WARNING，并附重试次数、降级策略执行情况
• 业务校验失败（如手机号格式错误）→ INFO 级别，属于正常流程分支，不应掩盖真正故障
• DEBUG 级别适合记录函数入口/出口、关键变量快照（开启时用，生产慎用）
• 配置日志等级时，确保 handler 的 level 不高于 logger 的 level，否则低级别日志会被静默丢弃

结构化日志 + 集中式收集更易排查

纯文本日志在多实例、高并发下难以检索。推荐输出 JSON 格式日志，配合 ELK 或 Loki 等工具做聚合分析。

• 用 python-json-logger 库替代默认 Formatter，一行一条 JSON，字段如 {"level": "ERROR", "time": "...", "funcName": "pay_order", "trace_id": "...", "msg": "支付回调验签失败"}
• 为每次请求生成唯一 trace_id，并在上下游服务间透传（如通过 HTTP Header），便于全链路追踪
• 在日志中记录耗时（如用 time.perf_counter() 打点），异常时一并输出，辅助判断是否超时引发连锁反应

本篇关于《Python异常日志记录与错误排查技巧》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！