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() со статусом=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–2024 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.12/library/faulthandler.html