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.

См. также

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