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.

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

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