27.2. 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中实现,因此traceback可以转储崩溃或当Python死锁。

27.2.1. Dumping the traceback

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

将所有线程的追踪转储到文件中。如果all_threadsFalse,则只转储当前线程。

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

27.2.2. Fault handler state

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

启用故障处理程序:安装SIGSEGVSIGFPESIGABRTSIGBUSSIGILL如果all_threadsTrue,则为每个正在运行的线程产生追溯。否则,只转储当前线程。

文件必须保持打开,直到故障处理程序被禁用:参见issue with file descriptors

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

faulthandler.disable()

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

faulthandler.is_enabled()

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

27.2.3. Dumping the tracebacks after a timeout

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

如果重复True,则在超时超时秒或每个超时如果退出True,则在转储跟踪后调用状态= 1的_exit()(注意_exit()立即退出该过程,这意味着它不会执行任何清理,如刷新文件缓冲区。)如果函数被调用两次,新调用将替换以前的参数并重置超时。定时器具有亚秒分辨率。

文件必须保持打开状态,直到调用traceback或调用cancel_dump_traceback_later():请参阅issue with file descriptors

此函数使用看门狗线程实现,因此如果Python编译时禁用线程,则不可用。

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

faulthandler.cancel_dump_traceback_later()

取消最后一次调用dump_traceback_later()

27.2.4. Dumping the traceback on a user signal

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

注册用户信号:为signum信号安装处理程序以转储所有线程或当前线程的跟踪(如果all_threadsFalse ,到文件如果chain为True,则调用上一个处理程序。

文件必须保持打开状态,直到unregister()未注册信号:请参阅文件描述器中的issue with file descriptors

在Windows上不可用。

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

faulthandler.unregister(signum)

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

在Windows上不可用。

27.2.5. Issue with file descriptors

enable()dump_traceback_later()register()保留其文件参数的文件描述器。如果文件关闭并且其文件描述器由一个新文件重用,或者如果os.dup2()用于替换文件描述器,则该追溯将被写入另一个文件。每次更换文件时都调用这些函数。

27.2.6. Example

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