faulthandler — Выгрузите трассировку Python

Added in version 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 Development Mode вызывает faulthandler.enable().

См.также

Модуль pdb

Интерактивный отладчик исходного кода для программ на Python.

Модуль traceback

Стандартный интерфейс для извлечения, форматирования и печати трасс стека программ на Python.

Выгрузка обратной трассировки

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

Сбросьте трассировки всех потоков в файл. Если 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, создаются трассировки для каждого запущенного потока. В противном случае будет произведен дамп только текущего потока.

Файл* должен оставаться открытым до тех пор, пока обработчик ошибок не будет отключен: см. раздел issue with file descriptors.

Изменено в версии 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(): см. issue with file descriptors.

Эта функция реализована с помощью потока сторожевого таймера.

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

Изменено в версии 3.7: Теперь эта функция доступна всегда.

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.

Файл* должен оставаться открытым до тех пор, пока сигнал не будет снят с регистрации с помощью unregister(): см. issue with file descriptors.

Недоступно для Windows.

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

faulthandler.unregister(signum)

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

Недоступно для Windows.

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

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

Пример

Пример ошибки сегментации в Linux с включением и без включения обработчика ошибок:

$ python -c "import ctypes; ctypes.string_at(0)"
Segmentation fault

$ python -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