faulthandler — 转储 Python 追踪

在版本 3.3 中添加。


此模块包含用于在故障、超时或用户信号上显式转储 Python 追踪的函数。调用 faulthandler.enable()SIGSEGVSIGFPESIGABRTSIGBUSSIGILL 信号安装故障处理程序。你还可以通过设置 PYTHONFAULTHANDLER 环境变量或使用 -X faulthandler 命令行选项在启动时启用它们。

故障处理程序与系统故障处理程序(如 Apport 或 Windows 故障处理程序)兼容。如果 sigaltstack() 函数可用,该模块将为信号处理程序使用备用堆栈。这允许它即使在堆栈溢出的情况下也能转储追踪。

故障处理程序在灾难性情况下被调用,因此只能使用信号安全函数(例如,它不能在堆上分配内存)。由于此限制,与正常的 Python 追踪相比,追踪转储是最小的

  • 仅支持 ASCII。在编码时使用 backslashreplace 错误处理程序。

  • 每个字符串限制为 500 个字符。

  • 仅显示文件名、函数名和行号。(无源代码)

  • 限制为 100 个帧和 100 个线程。

  • 顺序相反:最新调用最先显示。

默认情况下,Python 回溯写入 sys.stderr。要查看回溯,应用程序必须在终端中运行。或者,可以将日志文件传递给 faulthandler.enable()

该模块在 C 中实现,因此可以在崩溃或 Python 死锁时转储回溯。

Python 开发模式 在 Python 启动时调用 faulthandler.enable()

另请参阅

模块 pdb

Python 程序的交互式源代码调试器。

模块 traceback

用于提取、格式化和打印 Python 程序的堆栈跟踪的标准接口。

转储回溯

faulthandler.dump_traceback(file=sys.stderr, all_threads=True)

将所有线程的回溯转储到 file 中。如果 all_threadsFalse,则仅转储当前线程。

另请参阅

traceback.print_tb(),可用于打印回溯对象。

在 3.5 版中更改:添加了将文件描述符传递给此函数的支持。

错误处理程序状态

faulthandler.enable(file=sys.stderr, all_threads=True)

启用故障处理程序:为 SIGSEGVSIGFPESIGABRTSIGBUSSIGILL 信号安装处理程序,以转储 Python 回溯。如果 all_threadsTrue,则为正在运行的每个线程生成回溯。否则,仅转储当前线程。

必须保持 file 打开,直到故障处理程序被禁用:请参阅 文件描述符问题

在 3.5 版中更改:添加了将文件描述符传递给此函数的支持。

3.6 版中已更改:在 Windows 上,还安装了 Windows 异常处理程序。

3.10 版中已更改:如果 all_threads 为 true,则转储现在会提及垃圾收集器收集是否正在运行。

faulthandler.disable()

禁用故障处理程序:卸载 enable() 安装的信号处理程序。

faulthandler.is_enabled()

检查故障处理程序是否已启用。

在超时后转储回溯

faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)

在超时 timeout 秒后转储所有线程的回溯,或者在 repeatTrue 时每隔 timeout 秒转储一次。如果 exitTrue,则在转储回溯后使用 status=1 调用 _exit()。(注意 _exit() 立即退出进程,这意味着它不会执行任何清理操作,如刷新文件缓冲区。)如果该函数被调用两次,则新调用将替换先前的参数并重置超时。该计时器的分辨率为亚秒级。

文件必须保持打开状态,直到转储回溯或调用 cancel_dump_traceback_later():请参阅 文件描述符问题

此函数使用监视线程实现。

在 3.5 版中更改:添加了将文件描述符传递给此函数的支持。

在版本 3.7 中更改:此函数现在始终可用。

faulthandler.cancel_dump_traceback_later()

取消对 dump_traceback_later() 的最后一次调用。

在用户信号上转储回溯

faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)

注册用户信号:为 signum 信号安装一个处理程序,以便将所有线程的回溯(如果 all_threadsFalse,则为当前线程的回溯)转储到 file 中。如果 chain 为 True,则调用之前的处理程序。

文件必须保持打开状态,直到通过 unregister() 取消注册信号:请参阅 文件描述符问题

在 Windows 上不可用。

在 3.5 版中更改:添加了将文件描述符传递给此函数的支持。

faulthandler.unregister(signum)

取消注册用户信号:卸载由 register() 安装的 signum 信号的处理程序。如果已注册信号,则返回 True,否则返回 False

在 Windows 上不可用。

文件描述符问题

enable()dump_traceback_later()register() 保留其文件参数的文件描述符。如果文件已关闭且其文件描述符被新文件重新使用,或者如果使用 os.dup2() 替换文件描述符,则将回溯写入不同的文件。每次替换文件时,请再次调用这些函数。

示例

在 Linux 上启用和不启用故障处理程序的分段错误示例

$ python -c "import ctypes; ctypes.string_at(0)"
Segmentation fault

$ python -q -X faulthandler
>>> import ctypes
>>> ctypes.string_at(0)
Fatal Python error: Segmentation fault

Current thread 0x00007fb899f39700 (most recent call first):
  File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
  File "<stdin>", line 1 in <module>
Segmentation fault