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 (Режим разработки Python) вызывает faulthandler.enable() при запуске 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() со статусом 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.9/library/faulthandler.html