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 с включённым и выключенным обработчиком сбоев:

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

$ python3 -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.11/library/faulthandler.html