Содержание страницы

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

Этот модуль содержит функции для явного дампа трассировок 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.

Новое в версии 3.3.

27.2.1. Дамп трассировки¶Dump 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. Дамп трассировок по таймауту¶Dump 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. Дамп трассировки по сигналу пользователя¶Dump 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. Проблема с файловым дескриптором¶File descriptor issue

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

27.2.6. Пример¶Example

Пример ошибки сегментации в Linux:

$ python -q -X faulthandler
>>> import ctypes
>>> ctypes.string_at(0)
Fatal Python error: Segmentation fault

Current thread 0x00007fb899f39700:
  File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
  File "<stdin>", line 1 in <module>
Segmentation fault