faulthandler —转储 Pythontraceback

版本 3.3 中的新Function。

---

此模块包含一些函数，可在发生故障，超时或用户 signal 后显式转储 Python 跟踪。调用faulthandler.enable()为SIGSEGV，SIGFPE，SIGABRT，SIGBUS和SIGILLsignal 安装故障处理程序。您还可以在启动时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 *)
  • 启用错误处理程序：为SIGSEGV，SIGFPE，SIGABRT，SIGBUS和SIGILLsignal 安装处理程序，以转储 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()立即退出该进程，这意味着它不会像刷新文件缓冲区那样进行任何清理.)如果该函数被调用两次，则新调用将替换先前的参数并重置超时。计时器的分辨率为亚秒级。

• file *必须保持打开状态，直到转储回溯或调用cancel_dump_traceback_later()为止：请参阅文件 Descriptors 问题。

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

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

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

• faulthandler. cancel_dump_traceback_later ( )
  • 取消最后一次拨打dump_traceback_later()的电话。

将回溯转储到用户 signal 上

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

• file *必须保持打开状态，直到unregister()取消注册 signal 为止：请参见文件 Descriptors 问题。

在 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