faulthandler — вывод трассировки стека Python

Добавлено в версии 3.3.

Этот модуль содержит функции для явного вывода трассировок стека Python при сбое, по истечении времени ожидания или при получении пользовательского сигнала. Вызовите faulthandler.enable(), чтобы установить обработчики сбоев для сигналов SIGSEGV, SIGFPE, SIGABRT, SIGBUS и SIGILL. Их также можно включить при запуске, задав переменную среды PYTHONFAULTHANDLER или используя параметр командной строки -X faulthandler.

Обработчик сбоев совместим с системными обработчиками сбоев, такими как Apport или обработчик сбоев Windows. Если доступна функция sigaltstack(), модуль использует альтернативный стек для обработчиков сигналов. Это позволяет ему выводить трассировку стека даже при переполнении стека.

Обработчик сбоев вызывается в критических ситуациях и поэтому может использовать только функции, безопасные для сигналов (например, он не может выделять память в куче). Из-за этого ограничения вывод трассировки стека минимален по сравнению с обычными трассировками стека Python:

Поддерживается только ASCII. При кодировании используется обработчик ошибок backslashreplace.
Длина каждой строки ограничена 500 символами.
Отображаются только имя файла, имя функции и номер строки (без исходного кода).
Ограничение — 100 кадров и 100 потоков.
Порядок обратный: сначала показывается самый последний вызов.

По умолчанию трассировка стека Python записывается в sys.stderr. Чтобы увидеть трассировки стека, приложения необходимо запускать в терминале. Вместо этого в faulthandler.enable() можно передать файл журнала.

Модуль реализован на C, поэтому трассировки стека можно выводить при аварийном завершении или взаимной блокировке Python.

Режим разработки Python вызывает faulthandler.enable() при запуске Python.

См. также

Module pdb: Интерактивный отладчик исходного кода программ на Python.
Module traceback: Стандартный интерфейс для извлечения, форматирования и вывода трассировок стека программ на Python.

Вывод трассировки стека

faulthandler.dump_traceback(file=sys.stderr, all_threads=True): Вывести трассировки стека всех потоков в file. Если all_threads имеет значение False, вывести трассировку только текущего потока.

См. также

traceback.print_tb(), которую можно использовать для вывода объекта трассировки стека.

Изменено в версии 3.5: Добавлена поддержка передачи файлового дескриптора этой функции.

Вывод стека C

Добавлено в версии 3.14.

faulthandler.dump_c_stack(file=sys.stderr)

Вывести трассировку стека C текущего потока в file.

Если сборка Python не поддерживает эту возможность или операционная система не предоставляет трассировку стека, вместо стека C будет выведено сообщение об ошибке.

Совместимость со стеком C

Если система не поддерживает функции уровня C backtrace(3) или dladdr1(3), вывод стека C работать не будет. Вместо стека будет выведено сообщение об ошибке.

Кроме того, некоторые компиляторы не поддерживают реализацию вывода стека C в CPython. Поэтому вместо стека может быть выведено другое сообщение об ошибке, даже если операционная система поддерживает вывод стеков.

Примечание

Вывод стеков C может занимать сколь угодно много времени в зависимости от уровня DWARF двоичных файлов в стеке вызовов.

Состояние обработчика сбоев

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

Включить обработчик сбоев: установить обработчики сигналов SIGSEGV, SIGFPE, SIGABRT, SIGBUS и SIGILL для вывода трассировки стека Python. Если all_threads имеет значение True, вывести трассировки для всех работающих потоков. В противном случае вывести трассировку только текущего потока.

Файл file необходимо держать открытым до отключения обработчика сбоев: см. проблема с файловыми дескрипторами.

Если c_stack имеет значение True, после трассировки стека Python выводится трассировка стека C, если система поддерживает эту возможность. Дополнительные сведения о совместимости см. в описании dump_c_stack().

Изменено в версии 3.5: Добавлена поддержка передачи файлового дескриптора этой функции.

Изменено в версии 3.6: В Windows также устанавливается обработчик исключений Windows.

Изменено в версии 3.10: Теперь в выводе указывается, запущен ли сборщик мусора, если all_threads имеет значение true.

Изменено в версии 3.14: Если GIL отключён, выводится трассировка только текущего потока, чтобы предотвратить риск гонок данных.

Изменено в версии 3.14: Теперь при значении true для c_stack выводится трассировка стека C.

faulthandler.disable(): Отключить обработчик сбоев: удалить обработчики сигналов, установленные функцией enable().

faulthandler.is_enabled(): Проверить, включён ли обработчик сбоев.

Вывод трассировок стека по истечении времени ожидания

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

Вывести трассировки стека всех потоков по истечении timeout секунд или каждые timeout секунд, если repeat имеет значение True. Если exit имеет значение True, после вывода трассировок вызвать _exit() со значением status=1. (Обратите внимание: _exit() немедленно завершает процесс, то есть не выполняет очистку, например сброс буферов файлов.) При повторном вызове функции новые параметры заменяют предыдущие, а время ожидания отсчитывается заново. Таймер имеет разрешение меньше секунды.

Файл file необходимо держать открытым до вывода трассировки стека или вызова 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, в file. Вызвать предыдущий обработчик, если chain имеет значение True.

Файл file необходимо держать открытым до отмены регистрации сигнала функцией 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.14/_ctypes.cpython-314d-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.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x15a33 [0x77b7315e6a33]
  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x164fa [0x77b7315e74fa]
  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-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