Python traceback.TracebackException 怎么生成可控错误报告：异常链、局部变量与日志边界

线上任务失败时，直接把 traceback 打进日志往往不够可控：异常链可能被截断，局部变量又可能把口令、令牌或整份请求对象一起带出来。traceback.TracebackException 的价值在于先捕获一份适合后续展示的异常快照，再决定是否保留链路、局部变量和输出范围。

TracebackException 和直接打印 traceback 有什么不同

模块级的 traceback.print_exception() 适合马上写到标准错误；而 TracebackException 先把异常信息整理成轻量对象，之后可以调用 format()、print()，也可以把每一行交给结构化日志字段。它不会像直接保存 traceback 那样长期抓住 frame 和局部作用域。

import traceback

def build_report(exc: BaseException, *, show_chain: bool = True) -> str:
    snapshot = traceback.TracebackException.from_exception(
        exc,
        limit=8,
        capture_locals=False,
        compact=True,
    )
    return "".join(snapshot.format(chain=show_chain))

这里的 limit=8 是输出上限，不是修复异常的办法；它只让报告长度可预测。compact=True 适合先保存、后展示的路径，真正要输出时再调用 format()。

异常链要不要保留，取决于错误的归因目标

如果代码使用了 raise RuntimeError("同步失败") from exc，原始异常存在于 __cause__。默认 chain=True 会把原因一起格式化，排查数据库超时、解析失败这类二次包装错误时更有价值。

try:
    int("not-a-number")
except ValueError as exc:
    wrapped = RuntimeError("订单字段转换失败")
    wrapped.__cause__ = exc
    report = build_report(wrapped)
    print(report)

short_report = build_report(wrapped, show_chain=False)

对外返回的错误摘要通常只需 short_report 的当前异常；内部诊断日志保留完整链路。不要把完整 traceback 当成 API 响应，否则文件路径、代码行和内部字段可能直接暴露。

capture_locals=True 为什么容易把日志变成数据泄漏

捕获局部变量能帮助定位“参数在哪一步变坏”，但它会尝试记录每个栈帧里的局部值。局部值可能很大，也可能包含访问令牌、身份证号、请求体和数据库连接对象的 repr。这个开关应该是一次性的诊断选项，不应成为全局默认。

def diagnostic_report(exc: BaseException) -> str:
    snapshot = traceback.TracebackException.from_exception(
        exc,
        limit=5,
        capture_locals=True,
    )
    raw = "".join(snapshot.format(chain=True))
    return redact(raw)

def redact(text: str) -> str:
    for key in ("token", "password", "secret"):
        text = text.replace(key, "[masked]")
    return text[:12000]

示例中的替换只是演示边界，生产环境应按结构化字段脱敏，而不是依赖字符串替换。更稳妥的做法是默认 capture_locals=False，只有复现某类问题时在受控环境临时打开，并给日志设置最大长度。

几个参数的最小选择表

把异常报告接入日志时，先验证这四件事

1. 用一个带 from 的异常链测试 chain=True 与 chain=False 的差异。
2. 用包含 token 字段的局部变量测试脱敏，确认原值不会进入持久化日志。
3. 检查 limit 和最终字符串长度，避免异常风暴把单条日志放大。
4. 在 Python 3.11 及以上测试 ExceptionGroup 时，同时检查 max_group_width 与 max_group_depth 的截断效果。

常见问题

TracebackException 会自动修复异常吗？

不会。它只负责捕获和格式化异常信息，重试、降级和告警仍由业务代码决定。

capture_locals=True 能替代调试器吗？

不能。它只保存格式化所需的局部值表示，不能提供完整运行时状态，也不应绕过生产数据脱敏。

什么时候使用 chain=False？

对外展示或需要短错误摘要时可以使用；内部定位根因时通常保留默认链路。

为什么不直接保存 exc.__traceback__？

原始 traceback 可能继续持有 frame 和局部对象。需要延迟展示时，先转换为 TracebackException 更容易控制生命周期和输出内容。

小结

把异常捕获和异常展示拆开，才有机会同时做好根因保留与日志边界控制。常规路径使用 from_exception()、限制栈深并关闭局部变量；只有在受控诊断场景下临时打开 capture_locals，再经过脱敏、截断和链路核对。