faulthandler --- 傾印 Python 回溯

在 3.3 版被加入.

This module contains functions to dump Python tracebacks explicitly, on a fault,after a timeout, or on a user signal. Callfaulthandler.enable() toinstall fault handlers for theSIGSEGV,SIGFPE,SIGABRT,SIGBUS, andSIGILL signals. You can alsoenable them at startup by setting thePYTHONFAULTHANDLER environmentvariable or by using the-Xfaulthandler command line option.

The fault handler is compatible with system fault handlers like Apport or theWindows fault handler. The module uses an alternative stack for signal handlersif thesigaltstack() function is available. This allows it to dump thetraceback even on a stack overflow.

The fault handler is called on catastrophic cases and therefore can only usesignal-safe functions (e.g. it cannot allocate memory on the heap). Because ofthis limitation traceback dumping is minimal compared to normal Pythontracebacks:

  • Only ASCII is supported. Thebackslashreplace error handler is used onencoding.

  • Each string is limited to 500 characters.

  • Only the filename, the function name and the line number aredisplayed. (no source code)

  • It is limited to 100 frames and 100 threads.

  • The order is reversed: the most recent call is shown first.

By default, the Python traceback is written tosys.stderr. To seetracebacks, applications must be run in the terminal. A log file canalternatively be passed tofaulthandler.enable().

The module is implemented in C, so tracebacks can be dumped on a crash or whenPython is deadlocked.

ThePython Development Mode callsfaulthandler.enable()at Python startup.

也參考

pdb 模組

Interactive source code debugger for Python programs.

traceback 模組

Standard interface to extract, format and print stack traces of Python programs.

Dumping the traceback

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

Dump the tracebacks of all threads intofile. Ifall_threads isFalse, dump only the current thread.

也參考

traceback.print_tb(), which can be used to print a traceback object.

在 3.5 版的變更:Added support for passing file descriptor to this function.

Fault handler state

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

Enable the fault handler: install handlers for theSIGSEGV,SIGFPE,SIGABRT,SIGBUSandSIGILLsignals to dump the Python traceback. Ifall_threads isTrue,produce tracebacks for every running thread. Otherwise, dump only the currentthread.

Thefile must be kept open until the fault handler is disabled: seeissue with file descriptors.

在 3.5 版的變更:Added support for passing file descriptor to this function.

在 3.6 版的變更:On Windows, a handler for Windows exception is also installed.

在 3.10 版的變更:The dump now mentions if a garbage collector collection is runningifall_threads is true.

faulthandler.disable()

Disable the fault handler: uninstall the signal handlers installed byenable().

faulthandler.is_enabled()

Check if the fault handler is enabled.

Dumping the tracebacks after a timeout

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

Dump the tracebacks of all threads, after a timeout oftimeout seconds, oreverytimeout seconds ifrepeat isTrue. Ifexit isTrue, call_exit() with status=1 after dumping the tracebacks. (Note_exit() exits the process immediately, which means it doesn't do anycleanup like flushing file buffers.) If the function is called twice, the newcall replaces previous parameters and resets the timeout. The timer has asub-second resolution.

Thefile must be kept open until the traceback is dumped orcancel_dump_traceback_later() is called: seeissue with filedescriptors.

This function is implemented using a watchdog thread.

在 3.5 版的變更:Added support for passing file descriptor to this function.

在 3.7 版的變更:This function is now always available.

faulthandler.cancel_dump_traceback_later()

Cancel the last call todump_traceback_later().

Dumping the traceback on a user signal

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

Register a user signal: install a handler for thesignum signal to dumpthe traceback of all threads, or of the current thread ifall_threads isFalse, intofile. Call the previous handler if chain isTrue.

Thefile must be kept open until the signal is unregistered byunregister(): seeissue with file descriptors.

Not available on Windows.

在 3.5 版的變更:Added support for passing file descriptor to this function.

faulthandler.unregister(signum)

Unregister a user signal: uninstall the handler of thesignum signalinstalled byregister(). ReturnTrue if the signal was registered,False otherwise.

Not available on Windows.

Issue with file descriptors

enable(),dump_traceback_later() andregister() keep thefile descriptor of theirfile argument. If the file is closed and its filedescriptor is reused by a new file, or ifos.dup2() is used to replacethe file descriptor, the traceback will be written into a different file. Callthese functions again each time that the file is replaced.

範例

Example of a segmentation fault on Linux with and without enabling the faulthandler:

$python-c"import ctypes; ctypes.string_at(0)"Segmentation fault$python-q-Xfaulthandler>>> import ctypes>>> ctypes.string_at(0)Fatal Python error: Segmentation faultCurrent 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