Python logging 怎样让异常堆栈保留上下文

如果 except 日志只有“文件不存在”或“请求失败”，却没有出错行和调用路径，排查时往往只能重新猜测现场。Python 的 logging 已经提供了保留异常上下文的入口：在异常处理器里优先使用 logger.exception()；需要继续使用 error() 或自定义级别时，显式传入 exc_info=True。

先分清异常信息和调用栈

日志里常见的“上下文”有两种。异常回溯回答“异常从哪里抛出、经过哪些调用层返回”，由 exc_info 表达；当前调用栈回答“执行到这次 logging 调用时，当前线程的路径是什么”，由 stack_info 表达。排查一个已捕获的异常时，通常需要前者。

import logging

logger = logging.getLogger(__name__)

def load_config(path):
    # 这个函数只负责让调用者看到原始异常，不在这里吞掉上下文。
    with open(path, encoding="utf-8") as handle:
        return handle.read()

try:
    load_config("settings.toml")
except OSError:
    # 普通 error 只写消息，除非显式要求附带异常信息。
    logger.error("读取配置失败")

上面的日志可以说明“失败了”，但默认不会把 OSError 的 traceback 一起写出来。先把异常信息和当前调用栈分开，后面选择 API 时就不会把 stack_info=True 当成异常回溯的替代品。

在 except 中使用 logger.exception

Logger.exception() 会以 ERROR 级别记录消息，并把异常信息加入日志记录。它最适合放在当前 except 分支里，因为 logging 会从当前异常上下文取得回溯。

import logging

logger = logging.getLogger(__name__)

def read_settings(path):
    try:
        # 让真实的文件异常保留到 except，而不是先转换成普通字符串。
        with open(path, encoding="utf-8") as handle:
            return handle.read()
    except OSError:
        # exception 会保留异常类型、消息和 traceback。
        logger.exception("读取配置文件失败：path=%s", path)
        raise

这里的 path 是普通日志参数，最终由 Formatter 统一格式化；异常回溯则由 exc_info 进入 LogRecord。如果当前层只是记录并继续抛出，使用 raise 保持原异常链，避免日志有了上下文但业务错误被悄悄吞掉。

用 exc_info 控制非 exception 方法

有时日志级别来自配置，或者公共函数只能调用 logger.log(level, ...)。这时可以显式传入 exc_info=True，只要调用发生在异常处理器中，logging 就会读取当前异常信息。

import logging

logger = logging.getLogger(__name__)

try:
    value = int("not-a-number")
except ValueError:
    # 自定义级别仍保留当前 except 中的 traceback。
    logger.log(logging.ERROR, "输入转换失败", exc_info=True)

try:
    value = int("still-not-a-number")
except ValueError:
    # stack_info 描述当前调用路径，不替代 exc_info 的异常回溯。
    logger.error("输入转换失败", exc_info=True, stack_info=True)

exc_info=True 和传入异常元组的效果是让日志包含异常信息；在 Python 3.5 及以后，exc_info 也可以接收异常实例。若只是想知道“代码从哪里走到这里”，没有正在处理的异常，则单独考虑 stack_info=True。

补充请求上下文并避开常见误区

堆栈能告诉你代码位置，但生产排查通常还需要请求号、任务号或业务键。模块级 logger 用 __name__ 形成层级名称；额外字段可以通过 extra 放进 LogRecord，再由格式化器输出。

import logging

logger = logging.getLogger(__name__)

try:
    process_order("A-1024")
except Exception:
    # extra 的键要和 Formatter 中的字段保持一致，避免格式化时缺字段。
    logger.exception(
        "订单处理失败",
        extra={"request_id": "req-7f3", "order_id": "A-1024"},
    )

不要在 except 中只写 logger.error(str(exc))：它通常会丢掉 traceback。也不要在没有异常时调用 logger.exception() 期待它凭空生成原始错误；此时应使用普通级别方法，或按需要开启 stack_info。最后检查 Formatter 是否能容纳新增字段，并注意日志中的路径、请求参数和用户数据是否需要脱敏。

常见问题

logger.exception 为什么默认是 ERROR？

它是用于异常处理的便捷方法，语义上相当于 ERROR 日志并附加异常信息。如果业务确实需要别的级别，可以使用 logger.log(level, ..., exc_info=True)。

exc_info=True 和 stack_info=True 能同时使用吗？

可以，但它们记录的对象不同：前者是异常处理过程中的回溯，后者是当前线程到 logging 调用点的调用栈。只有在两类路径都对定位有帮助时才同时开启，以免日志过长。

因此，最稳妥的默认写法是：在异常处理器里用 logger.exception("说明：%s", value)，需要公共封装时改为 exc_info=True，再用 extra 补充可检索的业务上下文。