faulthandler —转储 Pythontraceback

版本 3.3 中的新Function。


此模块包含一些函数,可在发生故障,超时或用户 signal 后显式转储 Python 跟踪。调用faulthandler.enable()SIGSEGVSIGFPESIGABRTSIGBUSSIGILLsignal 安装故障处理程序。您还可以在启动时pass设置 PYTHONFAULTHANDLER环境变量或使用-X faulthandler命令行选项来启用它们。

故障处理程序与 Apport 或 Windows 故障处理程序等系统故障处理程序兼容。如果sigaltstack()Function可用,则模块将备用堆栈用于 signal 处理程序。这使它即使在堆栈溢出时也可以转储回溯。

故障处理程序在灾难性情况下被调用,因此只能使用 signal 安全Function(例如,它不能在堆上分配内存)。由于这个限制,与普通的 Python 回溯相比,回溯转储是最少的:

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

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

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

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

  • Sequences 相反:最近的呼叫首先显示。

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

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

转储 traceback

  • faulthandler. dump_traceback(* file = sys.stderr all_threads = True *)
    • 将所有线程的 traceback 转储到* file 中。如果 all_threads *为False,则仅转储当前线程。

在版本 3.5 中进行了更改:添加了对将文件 Descriptors 传递到此函数的支持。

故障处理程序状态

  • faulthandler. enable(* file = sys.stderr all_threads = True *)
    • 启用错误处理程序:为SIGSEGVSIGFPESIGABRTSIGBUSSIGILLsignal 安装处理程序,以转储 Python 回溯。如果* all_threads *为True,则为每个正在运行的线程生成回溯。否则,仅转储当前线程。

必须将* file *保持打开状态,直到禁用故障处理程序为止:请参见文件 Descriptors 问题

在版本 3.5 中进行了更改:添加了对将文件 Descriptors 传递到此函数的支持。

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

  • faulthandler. disable ( )

    • 禁用故障处理程序:卸载enable()安装的 signal 处理程序。
  • faulthandler. is_enabled ( )

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

超时后转储回溯

  • faulthandler. dump_traceback_later(* timeout repeat = False file = sys.stderr exit = False *)
    • 在* timeout 秒的超时之后,或者如果 repeat True,则每隔 timeout 秒转储所有线程的回溯。如果 exit *是True,则转储回溯后以状态= 1 调用_exit()。 (注意_exit()立即退出该进程,这意味着它不会像刷新文件缓冲区那样进行任何清理.)如果该函数被调用两次,则新调用将替换先前的参数并重置超时。计时器的分辨率为亚秒级。

此Function是使用看门狗线程实现的。

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

在版本 3.5 中进行了更改:添加了对将文件 Descriptors 传递到此函数的支持。

将回溯转储到用户 signal 上

  • faulthandler. register(* signum file = sys.stderr all_threads = True chain = False *)
    • 注册用户 signal:为* signum signal 安装处理程序,以将所有线程或当前线程(如果 all_threads False)的回溯转储到 file *中。如果 chain 为True,请调用上一个处理程序。

在 Windows 上不可用。

在版本 3.5 中进行了更改:添加了对将文件 Descriptors 传递到此函数的支持。

  • faulthandler. unregister(* signum *)
    • 取消注册用户 signal:卸载register()安装的* signum *signal 的处理程序。如果 signal 已注册,则返回True,否则返回False

在 Windows 上不可用。

文件 Descriptors 出现问题

enable()dump_traceback_later()register()保留其* file *参数的文件 Descriptors。如果文件已关闭并且其文件 Descriptors 被新文件重用,或者使用os.dup2()替换文件 Descriptors,则回溯将被写入另一个文件中。每次替换文件时,再次调用这些函数。

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