Документация 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 потоками (настраивается через max_threads).

  • Порядок обратный: сначала показывается самый последний вызов.

По умолчанию трассировка 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, *, max_threads=100)

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

См. также

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

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

Изменено в версии 3.15: Добавлен именованный аргумент max_threads.

Дамп 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, *, max_threads=100)

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

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

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

max_threads ограничивает количество потоков, выгружаемых при срабатывании фатального сигнала.

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

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

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

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

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

Изменено в версии 3.15: Добавлен именованный аргумент max_threads.

faulthandler.disable()

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

faulthandler.is_enabled()

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

Дамп трассировок по истечении тайм-аутаDumping the tracebacks after a timeout

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

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

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

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

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

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

Изменено в версии 3.15: Добавлен именованный аргумент max_threads.

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, *, max_threads=100)

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

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

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

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

Изменено в версии 3.15: Добавлен именованный аргумент max_threads.

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.15/_ctypes.cpython-315d-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.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0x15a33 [0x77b7315e6a33]
  Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0x164fa [0x77b7315e74fa]
  Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-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