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 Development Mode вызывает faulthandler.enable() при запуске 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, создаются трассировки для каждого запущенного потока. В противном случае создается дамп только для текущего потока.

Файл * должен оставаться открытым до тех пор, пока обработчик ошибок не будет отключен: см. раздел 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.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(): см. issue with file descriptors.

Недоступно для 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
bdb — Рамка отладчика
pdb — Отладчик Python
Вернуться на верх