faulthandler — Вывод отладочной информации Python

Этот модуль содержит функции для явного вывода отладочной информации 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.

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

faulthandler.dump_traceback(file=sys.stderr, all_threads=True)

Вывести отладочную информацию всех потоков в file. Если all_threads False, вывод только текущего потока.

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

27.2.2. Состояние обработчика ошибок

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()

Проверить, включен ли обработчик ошибок.

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

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(): см. проблемы с дескрипторами файлов.

Эта функция реализована с помощью потока-монитора и поэтому недоступна, если Python скомпилирован без поддержки потоков.

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

faulthandler.cancel_dump_traceback_later()

Отменить последний вызов dump_traceback_later().

27.2.4. Вывод отладочной информации при пользовательском сигнале

faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)

Зарегистрировать пользовательский сигнал: установить обработчик для сигнала signum для вывода отладочной информации всех потоков или текущего потока, если all_threads False, в file. Вызвать предыдущий обработчик, если цепочка True.

file должен оставаться открытым до момента отмены регистрации сигнала с помощью unregister(): см. проблемы с дескрипторами файлов.

Не доступно в Windows.

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

faulthandler.unregister(signum)

Отменить регистрацию пользовательского сигнала: удалить обработчик сигнала signum, установленный функцией register(). Вернуть True, если сигнал был зарегистрирован, False в противном случае.

Не доступно в Windows.

27.2.5. Проблемы с дескрипторами файлов

enable(), dump_traceback_later() и register() сохраняют дескриптор файла своего аргумента file. Если файл закрыт и его дескриптор повторно используется новым файлом, или если используется os.dup2() для замены дескриптора файла, отладочная информация будет записана в другой файл. Вызовите эти функции каждый раз, когда файл заменяется.

27.2.6. Пример

Пример сегментации памяти в 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