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: Добавлена поддержка передачи файлового дескриптора этой функции.

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

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

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

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

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

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

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

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 "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
  File "<stdin>", line 1 in <module>
Segmentation fault

© 2001–2025 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.13/library/faulthandler.html