| 1 |
:mod:`!faulthandler` --- Dump the Python traceback |
| 2 |
================================================== |
| 3 |
|
| 4 |
.. module:: faulthandler |
| 5 |
:synopsis: Dump the Python traceback. |
| 6 |
|
| 7 |
.. versionadded:: 3.3 |
| 8 |
|
| 9 |
---------------- |
| 10 |
|
| 11 |
This module contains functions to dump Python tracebacks explicitly, on a fault, |
| 12 |
after a timeout, or on a user signal. Call :func:`faulthandler.enable` to |
| 13 |
install fault handlers for the :const:`~signal.SIGSEGV`, |
| 14 |
:const:`~signal.SIGFPE`, :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS`, and |
| 15 |
:const:`~signal.SIGILL` signals. You can also |
| 16 |
enable them at startup by setting the :envvar:`PYTHONFAULTHANDLER` environment |
| 17 |
variable or by using the :option:`-X` ``faulthandler`` command line option. |
| 18 |
|
| 19 |
The fault handler is compatible with system fault handlers like Apport or the |
| 20 |
Windows fault handler. The module uses an alternative stack for signal handlers |
| 21 |
if the :c:func:`!sigaltstack` function is available. This allows it to dump the |
| 22 |
traceback even on a stack overflow. |
| 23 |
|
| 24 |
The fault handler is called on catastrophic cases and therefore can only use |
| 25 |
signal-safe functions (e.g. it cannot allocate memory on the heap). Because of |
| 26 |
this limitation traceback dumping is minimal compared to normal Python |
| 27 |
tracebacks: |
| 28 |
|
| 29 |
* Only ASCII is supported. The ``backslashreplace`` error handler is used on |
| 30 |
encoding. |
| 31 |
* Each string is limited to 500 characters. |
| 32 |
* Only the filename, the function name and the line number are |
| 33 |
displayed. (no source code) |
| 34 |
* It is limited to 100 frames and 100 threads. |
| 35 |
* The order is reversed: the most recent call is shown first. |
| 36 |
|
| 37 |
By default, the Python traceback is written to :data:`sys.stderr`. To see |
| 38 |
tracebacks, applications must be run in the terminal. A log file can |
| 39 |
alternatively be passed to :func:`faulthandler.enable`. |
| 40 |
|
| 41 |
The module is implemented in C, so tracebacks can be dumped on a crash or when |
| 42 |
Python is deadlocked. |
| 43 |
|
| 44 |
The :ref:`Python Development Mode <devmode>` calls :func:`faulthandler.enable` |
| 45 |
at Python startup. |
| 46 |
|
| 47 |
.. seealso:: |
| 48 |
|
| 49 |
Module :mod:`pdb` |
| 50 |
Interactive source code debugger for Python programs. |
| 51 |
|
| 52 |
Module :mod:`traceback` |
| 53 |
Standard interface to extract, format and print stack traces of Python programs. |
| 54 |
|
| 55 |
Dumping the traceback |
| 56 |
--------------------- |
| 57 |
|
| 58 |
.. function:: dump_traceback(file=sys.stderr, all_threads=True) |
| 59 |
|
| 60 |
Dump the tracebacks of all threads into *file*. If *all_threads* is |
| 61 |
``False``, dump only the current thread. |
| 62 |
|
| 63 |
.. seealso:: :func:`traceback.print_tb`, which can be used to print a traceback object. |
| 64 |
|
| 65 |
.. versionchanged:: 3.5 |
| 66 |
Added support for passing file descriptor to this function. |
| 67 |
|
| 68 |
|
| 69 |
Dumping the C stack |
| 70 |
------------------- |
| 71 |
|
| 72 |
.. versionadded:: 3.14 |
| 73 |
|
| 74 |
.. function:: dump_c_stack(file=sys.stderr) |
| 75 |
|
| 76 |
Dump the C stack trace of the current thread into *file*. |
| 77 |
|
| 78 |
If the Python build does not support it or the operating system |
| 79 |
does not provide a stack trace, then this prints an error in place |
| 80 |
of a dumped C stack. |
| 81 |
|
| 82 |
.. _c-stack-compatibility: |
| 83 |
|
| 84 |
C Stack Compatibility |
| 85 |
********************* |
| 86 |
|
| 87 |
If the system does not support the C-level :manpage:`backtrace(3)` |
| 88 |
or :manpage:`dladdr1(3)`, then C stack dumps will not work. |
| 89 |
An error will be printed instead of the stack. |
| 90 |
|
| 91 |
Additionally, some compilers do not support :term:`CPython's <CPython>` |
| 92 |
implementation of C stack dumps. As a result, a different error may be printed |
| 93 |
instead of the stack, even if the operating system supports dumping stacks. |
| 94 |
|
| 95 |
.. note:: |
| 96 |
|
| 97 |
Dumping C stacks can be arbitrarily slow, depending on the DWARF level |
| 98 |
of the binaries in the call stack. |
| 99 |
|
| 100 |
Fault handler state |
| 101 |
------------------- |
| 102 |
|
| 103 |
.. function:: enable(file=sys.stderr, all_threads=True, c_stack=True) |
| 104 |
|
| 105 |
Enable the fault handler: install handlers for the :const:`~signal.SIGSEGV`, |
| 106 |
:const:`~signal.SIGFPE`, :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS` |
| 107 |
and :const:`~signal.SIGILL` |
| 108 |
signals to dump the Python traceback. If *all_threads* is ``True``, |
| 109 |
produce tracebacks for every running thread. Otherwise, dump only the current |
| 110 |
thread. |
| 111 |
|
| 112 |
The *file* must be kept open until the fault handler is disabled: see |
| 113 |
:ref:`issue with file descriptors <faulthandler-fd>`. |
| 114 |
|
| 115 |
If *c_stack* is ``True``, then the C stack trace is printed after the Python |
| 116 |
traceback, unless the system does not support it. See :func:`dump_c_stack` for |
| 117 |
more information on compatibility. |
| 118 |
|
| 119 |
.. versionchanged:: 3.5 |
| 120 |
Added support for passing file descriptor to this function. |
| 121 |
|
| 122 |
.. versionchanged:: 3.6 |
| 123 |
On Windows, a handler for Windows exception is also installed. |
| 124 |
|
| 125 |
.. versionchanged:: 3.10 |
| 126 |
The dump now mentions if a garbage collector collection is running |
| 127 |
if *all_threads* is true. |
| 128 |
|
| 129 |
.. versionchanged:: 3.14 |
| 130 |
Only the current thread is dumped if the :term:`GIL` is disabled to |
| 131 |
prevent the risk of data races. |
| 132 |
|
| 133 |
.. versionchanged:: 3.14 |
| 134 |
The dump now displays the C stack trace if *c_stack* is true. |
| 135 |
|
| 136 |
.. function:: disable() |
| 137 |
|
| 138 |
Disable the fault handler: uninstall the signal handlers installed by |
| 139 |
:func:`enable`. |
| 140 |
|
| 141 |
.. function:: is_enabled() |
| 142 |
|
| 143 |
Check if the fault handler is enabled. |
| 144 |
|
| 145 |
|
| 146 |
Dumping the tracebacks after a timeout |
| 147 |
-------------------------------------- |
| 148 |
|
| 149 |
.. function:: dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False) |
| 150 |
|
| 151 |
Dump the tracebacks of all threads, after a timeout of *timeout* seconds, or |
| 152 |
every *timeout* seconds if *repeat* is ``True``. If *exit* is ``True``, call |
| 153 |
:c:func:`!_exit` with status=1 after dumping the tracebacks. (Note |
| 154 |
:c:func:`!_exit` exits the process immediately, which means it doesn't do any |
| 155 |
cleanup like flushing file buffers.) If the function is called twice, the new |
| 156 |
call replaces previous parameters and resets the timeout. The timer has a |
| 157 |
sub-second resolution. |
| 158 |
|
| 159 |
The *file* must be kept open until the traceback is dumped or |
| 160 |
:func:`cancel_dump_traceback_later` is called: see :ref:`issue with file |
| 161 |
descriptors <faulthandler-fd>`. |
| 162 |
|
| 163 |
This function is implemented using a watchdog thread. |
| 164 |
|
| 165 |
.. versionchanged:: 3.5 |
| 166 |
Added support for passing file descriptor to this function. |
| 167 |
|
| 168 |
.. versionchanged:: 3.7 |
| 169 |
This function is now always available. |
| 170 |
|
| 171 |
.. function:: cancel_dump_traceback_later() |
| 172 |
|
| 173 |
Cancel the last call to :func:`dump_traceback_later`. |
| 174 |
|
| 175 |
|
| 176 |
Dumping the traceback on a user signal |
| 177 |
-------------------------------------- |
| 178 |
|
| 179 |
.. function:: register(signum, file=sys.stderr, all_threads=True, chain=False) |
| 180 |
|
| 181 |
Register a user signal: install a handler for the *signum* signal to dump |
| 182 |
the traceback of all threads, or of the current thread if *all_threads* is |
| 183 |
``False``, into *file*. Call the previous handler if chain is ``True``. |
| 184 |
|
| 185 |
The *file* must be kept open until the signal is unregistered by |
| 186 |
:func:`unregister`: see :ref:`issue with file descriptors <faulthandler-fd>`. |
| 187 |
|
| 188 |
Not available on Windows. |
| 189 |
|
| 190 |
.. versionchanged:: 3.5 |
| 191 |
Added support for passing file descriptor to this function. |
| 192 |
|
| 193 |
.. function:: unregister(signum) |
| 194 |
|
| 195 |
Unregister a user signal: uninstall the handler of the *signum* signal |
| 196 |
installed by :func:`register`. Return ``True`` if the signal was registered, |
| 197 |
``False`` otherwise. |
| 198 |
|
| 199 |
Not available on Windows. |
| 200 |
|
| 201 |
|
| 202 |
.. _faulthandler-fd: |
| 203 |
|
| 204 |
Issue with file descriptors |
| 205 |
--------------------------- |
| 206 |
|
| 207 |
:func:`enable`, :func:`dump_traceback_later` and :func:`register` keep the |
| 208 |
file descriptor of their *file* argument. If the file is closed and its file |
| 209 |
descriptor is reused by a new file, or if :func:`os.dup2` is used to replace |
| 210 |
the file descriptor, the traceback will be written into a different file. Call |
| 211 |
these functions again each time that the file is replaced. |
| 212 |
|
| 213 |
|
| 214 |
Example |
| 215 |
------- |
| 216 |
|
| 217 |
Example of a segmentation fault on Linux with and without enabling the fault |
| 218 |
handler: |
| 219 |
|
| 220 |
.. code-block:: shell-session |
| 221 |
|
| 222 |
$ python -c "import ctypes; ctypes.string_at(0)" |
| 223 |
Segmentation fault |
| 224 |
|
| 225 |
$ python -q -X faulthandler |
| 226 |
>>> import ctypes |
| 227 |
>>> ctypes.string_at(0) |
| 228 |
Fatal Python error: Segmentation fault |
| 229 |
|
| 230 |
Current thread 0x00007fb899f39700 (most recent call first): |
| 231 |
File "/opt/python/Lib/ctypes/__init__.py", line 486 in string_at |
| 232 |
File "<stdin>", line 1 in <module> |
| 233 |
|
| 234 |
Current thread's C stack trace (most recent call first): |
| 235 |
Binary file "/opt/python/python", at _Py_DumpStack+0x42 [0x5b27f7d7147e] |
| 236 |
Binary file "/opt/python/python", at +0x32dcbd [0x5b27f7d85cbd] |
| 237 |
Binary file "/opt/python/python", at +0x32df8a [0x5b27f7d85f8a] |
| 238 |
Binary file "/usr/lib/libc.so.6", at +0x3def0 [0x77b73226bef0] |
| 239 |
Binary file "/usr/lib/libc.so.6", at +0x17ef9c [0x77b7323acf9c] |
| 240 |
Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0xcdf6 [0x77b7315dddf6] |
| 241 |
Binary file "/usr/lib/libffi.so.8", at +0x7976 [0x77b73158f976] |
| 242 |
Binary file "/usr/lib/libffi.so.8", at +0x413c [0x77b73158c13c] |
| 243 |
Binary file "/usr/lib/libffi.so.8", at ffi_call+0x12e [0x77b73158ef0e] |
| 244 |
Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x15a33 [0x77b7315e6a33] |
| 245 |
Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x164fa [0x77b7315e74fa] |
| 246 |
Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0xc624 [0x77b7315dd624] |
| 247 |
Binary file "/opt/python/python", at _PyObject_MakeTpCall+0xce [0x5b27f7b73883] |
| 248 |
Binary file "/opt/python/python", at +0x11bab6 [0x5b27f7b73ab6] |
| 249 |
Binary file "/opt/python/python", at PyObject_Vectorcall+0x23 [0x5b27f7b73b04] |
| 250 |
Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x490c [0x5b27f7cbb302] |
| 251 |
Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6] |
| 252 |
Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab] |
| 253 |
Binary file "/opt/python/python", at PyEval_EvalCode+0xc5 [0x5b27f7cd9ba3] |
| 254 |
Binary file "/opt/python/python", at +0x255957 [0x5b27f7cad957] |
| 255 |
Binary file "/opt/python/python", at +0x255ab4 [0x5b27f7cadab4] |
| 256 |
Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x6c3e [0x5b27f7cbd634] |
| 257 |
Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6] |
| 258 |
Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab] |
| 259 |
Binary file "/opt/python/python", at +0x11b6e1 [0x5b27f7b736e1] |
| 260 |
Binary file "/opt/python/python", at +0x11d348 [0x5b27f7b75348] |
| 261 |
Binary file "/opt/python/python", at +0x11d626 [0x5b27f7b75626] |
| 262 |
Binary file "/opt/python/python", at PyObject_Call+0x20 [0x5b27f7b7565e] |
| 263 |
Binary file "/opt/python/python", at +0x32a67a [0x5b27f7d8267a] |
| 264 |
Binary file "/opt/python/python", at +0x32a7f8 [0x5b27f7d827f8] |
| 265 |
Binary file "/opt/python/python", at +0x32ac1b [0x5b27f7d82c1b] |
| 266 |
Binary file "/opt/python/python", at Py_RunMain+0x31 [0x5b27f7d82ebe] |
| 267 |
<truncated rest of calls> |
| 268 |
Segmentation fault |