Документация 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.

См. также

Модуль pdb

Интерактивный отладчик исходного кода для программ на Python.

Модуль traceback

Стандартный интерфейс для извлечения, форматирования и вывода трассировок стека программ на Python.

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

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

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

См. также

traceback.print_tb(), который можно использовать для вывода объекта трассировки.

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

Дамп C-стекаDumping the C stack

Добавлено в версии 3.14.

faulthandler.dump_c_stack(file=sys.stderr)

Выгружает трассировку C-стека текущего потока в file.

Если сборка Python не поддерживает это или операционная система не предоставляет трассировку стека, то вместо дампа C-стека выводится сообщение об ошибке.

Совместимость C-стекаC Stack Compatibility

Если система не поддерживает backtrace(3) или dladdr1(3) на уровне C, то дампы C-стека работать не будут. Вместо стека будет выведена ошибка.

Кроме того, некоторые компиляторы не поддерживают реализацию дампов C-стека CPython. В результате вместо стека может быть выведена другая ошибка, даже если операционная система поддерживает дампы стеков.

Примечание

Дампы C-стеков могут быть сколь угодно медленными в зависимости от уровня DWARF бинарных файлов в стеке вызовов.

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

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

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

Файл file должен оставаться открытым, пока обработчик сбоев не отключён: см. проблему с файловыми дескрипторами.

Если c_stack равен True, то стек C выводится после трассировки Python, если только система это не поддерживает. Дополнительную информацию о совместимости см. в dump_c_stack().

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

Изменено в версии 3.6: В Windows также устанавливается обработчик для исключений Windows.

Изменено в версии 3.10: В дампе теперь указывается, выполняется ли сборка мусора, если all_threads равен true.

Изменено в версии 3.14: Если GIL отключён, дампится только текущий поток, чтобы избежать риска состояния гонки.

Изменено в версии 3.14: Теперь в дампе отображается стек C, если c_stack равен true.

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.5: Добавлена поддержка передачи файлового дескриптора в эту функцию.

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

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 при включённом и выключенном обработчике ошибок:

$ python -c "import ctypes; ctypes.string_at(0)"
Segmentation fault

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

Current thread 0x00007fb899f39700 (most recent call first):
  File "/opt/python/Lib/ctypes/__init__.py", line 486 in string_at
  File "<stdin>", line 1 in <module>

Current thread's C stack trace (most recent call first):
  Binary file "/opt/python/python", at _Py_DumpStack+0x42 [0x5b27f7d7147e]
  Binary file "/opt/python/python", at +0x32dcbd [0x5b27f7d85cbd]
  Binary file "/opt/python/python", at +0x32df8a [0x5b27f7d85f8a]
  Binary file "/usr/lib/libc.so.6", at +0x3def0 [0x77b73226bef0]
  Binary file "/usr/lib/libc.so.6", at +0x17ef9c [0x77b7323acf9c]
  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0xcdf6 [0x77b7315dddf6]
  Binary file "/usr/lib/libffi.so.8", at +0x7976 [0x77b73158f976]
  Binary file "/usr/lib/libffi.so.8", at +0x413c [0x77b73158c13c]
  Binary file "/usr/lib/libffi.so.8", at ffi_call+0x12e [0x77b73158ef0e]
  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x15a33 [0x77b7315e6a33]
  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x164fa [0x77b7315e74fa]
  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0xc624 [0x77b7315dd624]
  Binary file "/opt/python/python", at _PyObject_MakeTpCall+0xce [0x5b27f7b73883]
  Binary file "/opt/python/python", at +0x11bab6 [0x5b27f7b73ab6]
  Binary file "/opt/python/python", at PyObject_Vectorcall+0x23 [0x5b27f7b73b04]
  Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x490c [0x5b27f7cbb302]
  Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
  Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
  Binary file "/opt/python/python", at PyEval_EvalCode+0xc5 [0x5b27f7cd9ba3]
  Binary file "/opt/python/python", at +0x255957 [0x5b27f7cad957]
  Binary file "/opt/python/python", at +0x255ab4 [0x5b27f7cadab4]
  Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x6c3e [0x5b27f7cbd634]
  Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
  Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
  Binary file "/opt/python/python", at +0x11b6e1 [0x5b27f7b736e1]
  Binary file "/opt/python/python", at +0x11d348 [0x5b27f7b75348]
  Binary file "/opt/python/python", at +0x11d626 [0x5b27f7b75626]
  Binary file "/opt/python/python", at PyObject_Call+0x20 [0x5b27f7b7565e]
  Binary file "/opt/python/python", at +0x32a67a [0x5b27f7d8267a]
  Binary file "/opt/python/python", at +0x32a7f8 [0x5b27f7d827f8]
  Binary file "/opt/python/python", at +0x32ac1b [0x5b27f7d82c1b]
  Binary file "/opt/python/python", at Py_RunMain+0x31 [0x5b27f7d82ebe]
  <truncated rest of calls>
Segmentation fault