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.

Вывод отладочной информации о трейсе

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

Изменено в версии 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.

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.7: Эта функция теперь всегда доступна.

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

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–2022 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.8/library/faulthandler.html