Документация Python неофициальный перевод
Содержание страницы

27.2. faulthandler – Дамп трассировки Pythonfaulthandler – Dump the Python traceback

Новое в версии 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.

27.2.1. Вывод трассировкиDumping the traceback

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

Выводит трассировки всех потоков в file. Если all_threads равно False, выводится только текущий поток.

27.2.2. Состояние обработчика сбоевFault handler state

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

Включает обработчик сбоев: устанавливает обработчики для сигналов SIGSEGV, SIGFPE, SIGABRT, SIGBUS и SIGILL для вывода трассировки Python. Если all_threads равно True, создаются трассировки для каждого работающего потока. В противном случае выводится только текущий поток.

faulthandler.disable()

Отключает обработчик сбоев: удаляет обработчики сигналов, установленные вызовом enable().

faulthandler.is_enabled()

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

27.2.3. Вывод трассировок после тайм-аутаDumping the tracebacks after a timeout

faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)

Выводит трассировки всех потоков по истечении timeout секунд или каждые timeout секунд, если repeat равно True. Если exit равно True, вызывает _exit() с status=1 после вывода трассировок. (Обратите внимание: _exit() немедленно завершает процесс, то есть не выполняет никакой очистки, например сброса буферов файлов.) Если функция вызывается дважды, новый вызов заменяет предыдущие параметры и сбрасывает таймер. Таймер имеет субсекундное разрешение.

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

faulthandler.cancel_dump_traceback_later()

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

27.2.4. Вывод трассировки по сигналу пользователяDumping the traceback on a user signal

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

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

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

faulthandler.unregister(signum)

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

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

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

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

27.2.6. ПримерExample

Пример ошибки сегментации в 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