# `faulthandler` — Dump the Python traceback

Added in version 3.3.

This module contains functions to dump Python tracebacks explicitly, on a fault, after a timeout, or on a user signal. Call `faulthandler.enable()` to install fault handlers for the `SIGSEGV`, `SIGFPE`, `SIGABRT`, `SIGBUS`, and `SIGILL` signals. You can also enable them at startup by setting the `PYTHONFAULTHANDLER` environment variable or by using the `-X` `faulthandler` command line option.

The fault handler is compatible with system fault handlers like Apport or the Windows fault handler. The module uses an alternative stack for signal handlers if the `sigaltstack()` function is available. This allows it to dump the traceback even on a stack overflow.

Обробник помилок викликається в катастрофічних випадках і тому може використовувати лише безпечні для сигналу функції (наприклад, він не може виділяти пам’ять у купі). Через це обмеження дамп зворотного відстеження мінімальний порівняно зі звичайним відстеженням Python:

- Підтримується лише ASCII. Під час кодування використовується обробник помилок `backslashreplace`.

- Довжина кожного рядка обмежена 500 символами.

- Відображаються лише назва файлу, назва функції та номер рядка. (без вихідного коду)

- It is limited to 100 frames per thread, and 100 threads (configurable via max_threads).

- Порядок зворотний: останній виклик відображається першим.

За замовчуванням відстеження Python записується в `sys.stderr`. Щоб побачити відстеження, програми мають бути запущені в терміналі. Файл журналу також можна передати до `faulthandler.enable()`.

Модуль реалізовано на C, тому трасування можна скинути під час збою або коли Python заблоковано.

Режим розробки Python викликає `faulthandler.enable()` під час запуску Python.

Дивись також

Module `pdb`

  Interactive source code debugger for Python programs.

Module `traceback`

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

## Викидання трасування

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

  Dump the tracebacks of all threads into file. If all_threads is `False`, dump only the current thread. max_threads caps the number of threads dumped.

  Дивись також

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

  Змінено в версії 3.5: Додано підтримку для передачі дескриптора файлу в цю функцію.

  Змінено в версії 3.15: Added the max_threads keyword argument.

## Dumping the C stack

Added in version 3.14.

faulthandler.dump_c_stack(file=sys.stderr)

  Dump the C stack trace of the current thread into file.

  If the Python build does not support it or the operating system does not provide a stack trace, then this prints an error in place of a dumped C stack.

### C Stack Compatibility

If the system does not support the C-level backtrace(3) or dladdr1(3), then C stack dumps will not work. An error will be printed instead of the stack.

Additionally, some compilers do not support CPython’s implementation of C stack dumps. As a result, a different error may be printed instead of the stack, even if the operating system supports dumping stacks.

Примітка

Dumping C stacks can be arbitrarily slow, depending on the DWARF level of the binaries in the call stack.

## Стан обробника помилок

faulthandler.enable(file=sys.stderr, all_threads=True, c_stack=True, *, max_threads=100)

  Enable the fault handler: install handlers for the `SIGSEGV`, `SIGFPE`, `SIGABRT`, `SIGBUS` and `SIGILL` signals to dump the Python traceback. If all_threads is `True`, produce tracebacks for every running thread. Otherwise, dump only the current thread.

  Файл має бути відкритим, доки обробник помилок не буде вимкнено: див. проблему з дескрипторами файлів.

  If c_stack is `True`, then the C stack trace is printed after the Python traceback, unless the system does not support it. See `dump_c_stack()` for more information on compatibility.

  max_threads caps the number of threads dumped when a fatal signal fires.

  Змінено в версії 3.5: Додано підтримку для передачі дескриптора файлу в цю функцію.

  Змінено в версії 3.6: У Windows також встановлено обробник винятків Windows.

  Змінено в версії 3.10: Дамп тепер згадує, чи запущено збирач сміття, якщо all_threads має значення true.

  Змінено в версії 3.14: Only the current thread is dumped if the GIL is disabled to prevent the risk of data races.

  Змінено в версії 3.14: The dump now displays the C stack trace if c_stack is true.

  Змінено в версії 3.15: Added the max_threads keyword argument.

faulthandler.disable()

  Вимкніть обробник помилок: видаліть обробники сигналів, встановлені `enable()`.

faulthandler.is_enabled()

  Перевірте, чи ввімкнено обробник помилок.

## Викидання трасування після тайм-ауту

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

  Dump the tracebacks of all threads, after a timeout of timeout seconds, or every timeout seconds if repeat is `True`. If exit is `True`, call `_exit()` with status=1 after dumping the tracebacks. (Note `_exit()` exits the process immediately, which means it doesn’t do any cleanup like flushing file buffers.) If the function is called twice, the new call replaces previous parameters and resets the timeout. The timer has a sub-second resolution. max_threads caps the number of threads dumped.

  Файл має залишатися відкритим, доки не буде створено дамп трасування або `cancel_dump_traceback_later()`: див. проблему з дескрипторами файлів.

  Ця функція реалізована за допомогою сторожового потоку.

  Змінено в версії 3.5: Додано підтримку для передачі дескриптора файлу в цю функцію.

  Змінено в версії 3.7: Тепер ця функція доступна завжди.

  Змінено в версії 3.15: Added the max_threads keyword argument.

faulthandler.cancel_dump_traceback_later()

  Скасувати останній виклик `dump_traceback_later()`.

## Скидання зворотного відстеження за сигналом користувача

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

  Register a user signal: install a handler for the signum signal to dump the traceback of all threads, or of the current thread if all_threads is `False`, into file. Call the previous handler if chain is `True`. max_threads caps the number of threads dumped.

  Файл має залишатися відкритим, доки сигнал не буде скасовано `unregister()`: див. проблему з дескрипторами файлів.

  Недоступно в Windows.

  Змінено в версії 3.5: Додано підтримку для передачі дескриптора файлу в цю функцію.

  Змінено в версії 3.15: Added the max_threads keyword argument.

faulthandler.unregister(signum)

  Скасувати реєстрацію сигналу користувача: видалити обробник сигналу signum, встановлений `register()`. Повертає `True`, якщо сигнал був зареєстрований, `False` інакше.

  Недоступно в Windows.

## Проблема з дескрипторами файлів

`enable()`, `dump_traceback_later()` і `register()` зберігають файловий дескриптор свого аргументу file. Якщо файл закрито і його файловий дескриптор повторно використовується в новому файлі, або якщо `os.dup2()` використовується для заміни файлового дескриптора, трасування буде записане в інший файл. Викликайте ці функції знову щоразу, коли файл замінюється.

## приклад

Приклад помилки сегментації в Linux із увімкненням і без увімкнення обробника помилок:

    $ python -c "import ctypes; ctypes.string_at(0)"
    Segmentation fault

    $ python -q -X faulthandler
    >>> import ctypes
    >>> ctypes.string_at(0)
    Fatal Python error: Segmentation fault

    Current thread 0x00007fb899f39700 (most recent call first):
      File "/opt/python/Lib/ctypes/__init__.py", line 486 in string_at
      File "<stdin>", line 1 in <module>

    Current thread's C stack trace (most recent call first):
      Binary file "/opt/python/python", at _Py_DumpStack+0x42 [0x5b27f7d7147e]
      Binary file "/opt/python/python", at +0x32dcbd [0x5b27f7d85cbd]
      Binary file "/opt/python/python", at +0x32df8a [0x5b27f7d85f8a]
      Binary file "/usr/lib/libc.so.6", at +0x3def0 [0x77b73226bef0]
      Binary file "/usr/lib/libc.so.6", at +0x17ef9c [0x77b7323acf9c]
      Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0xcdf6 [0x77b7315dddf6]
      Binary file "/usr/lib/libffi.so.8", at +0x7976 [0x77b73158f976]
      Binary file "/usr/lib/libffi.so.8", at +0x413c [0x77b73158c13c]
      Binary file "/usr/lib/libffi.so.8", at ffi_call+0x12e [0x77b73158ef0e]
      Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0x15a33 [0x77b7315e6a33]
      Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0x164fa [0x77b7315e74fa]
      Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0xc624 [0x77b7315dd624]
      Binary file "/opt/python/python", at _PyObject_MakeTpCall+0xce [0x5b27f7b73883]
      Binary file "/opt/python/python", at +0x11bab6 [0x5b27f7b73ab6]
      Binary file "/opt/python/python", at PyObject_Vectorcall+0x23 [0x5b27f7b73b04]
      Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x490c [0x5b27f7cbb302]
      Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
      Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
      Binary file "/opt/python/python", at PyEval_EvalCode+0xc5 [0x5b27f7cd9ba3]
      Binary file "/opt/python/python", at +0x255957 [0x5b27f7cad957]
      Binary file "/opt/python/python", at +0x255ab4 [0x5b27f7cadab4]
      Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x6c3e [0x5b27f7cbd634]
      Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
      Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
      Binary file "/opt/python/python", at +0x11b6e1 [0x5b27f7b736e1]
      Binary file "/opt/python/python", at +0x11d348 [0x5b27f7b75348]
      Binary file "/opt/python/python", at +0x11d626 [0x5b27f7b75626]
      Binary file "/opt/python/python", at PyObject_Call+0x20 [0x5b27f7b7565e]
      Binary file "/opt/python/python", at +0x32a67a [0x5b27f7d8267a]
      Binary file "/opt/python/python", at +0x32a7f8 [0x5b27f7d827f8]
      Binary file "/opt/python/python", at +0x32ac1b [0x5b27f7d82c1b]
      Binary file "/opt/python/python", at Py_RunMain+0x31 [0x5b27f7d82ebe]
      <truncated rest of calls>
    Segmentation fault