Python logging 的 stacklevel：日志已经输出，为什么每条都指向同一个包装函数
项目把统一日志格式放进一个辅助函数，业务代码调用它时文字都正确，文件名和行号却总是指向那几行公共代码。排查导入失败时，每个入口看起来都像来自同一个地方。因为日志默认记录的是实际调用日志接口的位置；包装层已经变成这个位置，格式化器并不知道你真正想看它的调用者。
stacklevel 可以让日志在确定来源时越过辅助层。它从 Python 三点八开始提供，默认值是一；对于直接调用日志方法的一层普通包装器，设置为二可以指向外面的业务调用。下面不依赖终端格式，而是直接捕获 LogRecord，保存为 demo.py 后运行 python demo.py。
AI生成概念插图：来源指针越过辅助层，指向真正发起动作的一端；不是日志平台或运行截图。
import inspect
import logging
records = []
class Capture(logging.Handler):
def emit(self, record):
records.append(record)
logger = logging.getLogger("batch25.stacklevel")
logger.setLevel(logging.INFO)
logger.propagate = False
handler = Capture()
logger.addHandler(handler)
def plain_wrapper():
logger.info("plain")
def shifted_wrapper():
logger.info("shifted", stacklevel=2)
def caller():
plain_wrapper()
expected_line = inspect.currentframe().f_lineno + 1
shifted_wrapper()
return expected_line
try:
expected = caller()
assert len(records) == 2
assert records[0].funcName == "plain_wrapper"
assert records[1].funcName == "caller"
assert records[1].lineno == expected
print("plain source:", records[0].funcName)
print("shifted source:", records[1].funcName)
print("line matched:", records[1].lineno == expected)
finally:
logger.removeHandler(handler)
handler.close()直接检查记录，而不是只看打印样式
第一条记录的 funcName 是 plain_wrapper，第二条则是 caller，最后 line matched 输出 True。两条日志经过同一个处理器，因此差异不是模板变了，而是记录创建时选择了不同的调用位置。示例还动态记下预期行号，让你在代码前面增加注释以后，验证仍然成立。
这个做法适合回归检查日志辅助库。只断言出现某句话，无法发现文件名或行号已经偏了一层；只检查日志级别同样不够。捕获记录后核对 funcName、lineno 和必要的 pathname，才能直接验证开发者点击日志时会落到哪里。输出的数字会随文件布局变化，不应该在文章外机械地固定。
示例创建独立名称的 logger，并关闭向父级传播，只是为了让两条观测不受外部日志配置影响。正式项目应遵循自身配置方式，不需要在每个辅助函数里重新添加处理器。收尾明确移除并关闭本次创建的处理器，避免在同一解释器再次运行时积累重复输出。
包装层变多时，需要一起维护约定
如果调用链后来变成业务函数、外层辅助函数、内层辅助函数，再到 logger，原先固定的二就可能只跳到外层辅助函数。更通用的包装接口可以接收 stacklevel 并在继续转发时加一，让每层只负责自己的那一层。无论采用哪种方式，都应在真实调用形状下验证，而不是把一个很大的数当成万能设置。
stacklevel 调整的是日志记录里的来源位置，不会改写程序控制流，也不会把任意异常的堆栈重新定位。需要保存异常信息时仍使用相应的异常日志参数；需要附上当前调用栈则另看 stack_info。三个需求可以同时存在，但每个参数回答的问题不同，不应因为名字里都有 stack 就互相替换。
还要区分日志发生位置与业务来源。如果任务先进入队列，稍后由另一个工作函数记录日志，向上跳调用栈只能找到那次实际调用的上层，不能自动回到早已结束的提交入口。此时应在任务数据里保存请求编号或来源信息，再作为独立字段记录，不能靠不断增加层数重建历史。
调整现有辅助库之前，选择一个直接调用、一个经过一层包装、一个经过两层包装的场景，把预期函数名写成测试。以后重构包装层、改用适配器或者增加装饰器，都重新检查这几个观察点。这样修复的是可追踪的位置约定，而不只是让当前这一条日志看起来更顺眼。
资料核对日期：2026年10月2日（北京时间）。示例在本地 Python 3.12.14 实际运行并通过断言，结果仅对应文中给定输入。
