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 символами.

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

  • Він обмежений 100 кадрами та 100 потоками.

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

За замовчуванням відстеження 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)

Дамп трасування всіх потоків у файл. Якщо all_threads має значення False, створювати дамп лише поточного потоку.

Дивись також

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

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

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)

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.

Змінено в версії 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.

faulthandler.disable()

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

faulthandler.is_enabled()

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

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

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

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.

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

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

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

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

faulthandler.cancel_dump_traceback_later()

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

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

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

Зареєструйте сигнал користувача: встановіть обробник для сигналу signum, щоб скинути зворотне трасування всіх потоків або поточного потоку, якщо all_threads має значення False, у файл. Викликати попередній обробник, якщо ланцюжок має значення True.

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

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

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

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