faulthandler — 转储 Python 回溯 — Python 文档
faulthandler — 转储 Python 回溯
3.3 版中的新功能。
该模块包含显式转储 Python 回溯、故障、超时或用户信号的函数。 调用 faulthandler.enable() 为 SIGSEGV
、SIGFPE
、SIGABRT
、SIGBUS
和 SIGILL
信号。 您还可以通过设置 PYTHONFAULTHANDLER 环境变量或使用 -X faulthandler
命令行选项在启动时启用它们。
故障处理程序与系统故障处理程序(如 Apport 或 Windows 故障处理程序)兼容。 如果 sigaltstack()
函数可用,该模块使用信号处理程序的替代堆栈。 这允许它即使在堆栈溢出时也可以转储回溯。
故障处理程序在灾难性情况下被调用,因此只能使用信号安全功能(例如 它不能在堆上分配内存)。 由于这个限制,与普通的 Python 回溯相比,回溯转储是最小的:
- 仅支持 ASCII。
backslashreplace
错误处理程序用于编码。 - 每个字符串限制为 500 个字符。
- 只显示文件名、函数名和行号。 (没有源代码)
- 它被限制为 100 帧和 100 个线程。
- 顺序相反:最先显示最近的呼叫。
默认情况下,Python 回溯被写入 sys.stderr。 要查看回溯,应用程序必须在终端中运行。 日志文件也可以传递给 faulthandler.enable()。
该模块是用 C 实现的,因此可以在崩溃或 Python 死锁时转储回溯。
Python 开发模式 在 Python 启动时调用 faulthandler.enable()。
转储回溯
- faulthandler.dump_traceback(file=sys.stderr, all_threads=True)
将所有线程的回溯转储到 文件 中。 如果 all_threads 是
False
,则只转储当前线程。在 3.5 版更改: 添加了对将文件描述符传递给此函数的支持。
故障处理程序状态
- faulthandler.enable(file=sys.stderr, all_threads=True)
启用故障处理程序:为
SIGSEGV
、SIGFPE
、SIGABRT
、SIGBUS
和SIGILL
信号安装处理程序以转储 Python 回溯。 如果 all_threads 是True
,则为每个正在运行的线程生成回溯。 否则,仅转储当前线程。文件 必须保持打开状态,直到故障处理程序被禁用:参见 文件描述符问题 。
在 3.5 版更改: 添加了对将文件描述符传递给此函数的支持。
3.6 版更改: 在 Windows 上,还安装了 Windows 异常处理程序。
在 3.10 版更改:如果 all_threads 为真,转储现在会提到垃圾收集器收集是否正在运行。
- faulthandler.disable()
- 禁用故障处理程序:卸载由 enable() 安装的信号处理程序。
- faulthandler.is_enabled()
- 检查是否启用了故障处理程序。
超时后转储回溯
- faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)
如果 repeat 是
True
,则在 timeout 秒超时后或每隔 timeout 秒转储所有线程的回溯。 如果 exit 是True
,则在转储回溯后以 status=1 调用_exit()
。 (注意_exit()
会立即退出进程,这意味着它不会像刷新文件缓冲区那样进行任何清理。)如果该函数被调用两次,新调用将替换之前的参数并重置超时。 计时器具有亚秒级分辨率。文件 必须保持打开状态,直到回溯被转储或 cancel_dump_traceback_later() 被调用:参见 文件描述符问题 。
此功能是使用看门狗线程实现的。
3.7 版本变更: 此功能现在一直可用。
在 3.5 版更改: 添加了对将文件描述符传递给此函数的支持。
- faulthandler.cancel_dump_traceback_later()
- 取消对 dump_traceback_later() 的最后一次调用。
将回溯转储到用户信号上
- faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)
注册用户信号:为 signum 信号安装一个处理程序以转储所有线程的回溯,如果 all_threads 是
False
,则转储当前线程的回溯到 ]文件。 如果链是True
,则调用前一个处理程序。file 必须保持打开状态,直到信号被 unregister() 取消注册:参见 文件描述符问题 。
在 Windows 上不可用。
在 3.5 版更改: 添加了对将文件描述符传递给此函数的支持。
- faulthandler.unregister(signum)
注销用户信号:卸载register()安装的signum信号处理程序。 如果信号已注册,则返回
True
,否则返回False
。在 Windows 上不可用。
文件描述符问题
enable()、dump_traceback_later() 和 register() 保留其 file 参数的文件描述符。 如果文件被关闭并且其文件描述符被新文件重用,或者如果使用 os.dup2() 替换文件描述符,则回溯将写入不同的文件。 每次替换文件时再次调用这些函数。
示例
启用和不启用故障处理程序的 Linux 上的分段故障示例:
$ python3 -c "import ctypes; ctypes.string_at(0)"
Segmentation fault
$ python3 -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