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

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.

Режим разработки Python вызывает faulthandler.enable() при запуске Python.

Дамп трассировкиDumping the traceback

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

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

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

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

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()

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

Дамп трассировок по истечении тайм-аута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() с кодом завершения 1 после вывода трассировок. (Обратите внимание, что _exit() завершает процесс немедленно, не выполняя никакой очистки, например, сброса буферов файлов.) Если функция вызывается дважды, новый вызов заменяет предыдущие параметры и сбрасывает таймер. Таймер имеет субсекундное разрешение.

Файл file должен оставаться открытым до тех пор, пока не будет выведена трассировка или не будет вызвана cancel_dump_traceback_later(): см. проблему с файловыми дескрипторами.

Эта функция реализована с использованием потока-наблюдателя.

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

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

faulthandler.cancel_dump_traceback_later()

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

Дамп трассировки по сигналу пользователяDumping the traceback on a user signal

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

Register a user signal: install a handler for the signum signal to dump the traceback of all threads, or of the current thread if all_threads is False, into file. Call the previous handler if chain is True.

Файл file должен оставаться открытым до тех пор, пока сигнал не будет отменён вызовом unregister(): см. проблему с файловыми дескрипторами.

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

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

faulthandler.unregister(signum)

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

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

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

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

Пример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