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 намертво заблокирован (deadlocked).

Дамп трейсбэка

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. Вызвать предыдущий обработчик, если цепочка 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