`faulthandler.md`

194 строк · 17.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3/library/faulthandler.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `faulthandler` – Дамп трассировки Python89Добавлено в версии 3.3.1011---1213Этот модуль содержит функции для явного дампа трассировок Python при сбое, по истечении времени ожидания или по сигналу пользователя. Вызов [`faulthandler.enable()`](https://python-all.ru/3/library/faulthandler.html#faulthandler.enable) устанавливает обработчики сбоев для сигналов [`SIGSEGV`](https://python-all.ru/3/library/signal.html#signal.SIGSEGV), [`SIGFPE`](https://python-all.ru/3/library/signal.html#signal.SIGFPE), [`SIGABRT`](https://python-all.ru/3/library/signal.html#signal.SIGABRT), [`SIGBUS`](https://python-all.ru/3/library/signal.html#signal.SIGBUS) и [`SIGILL`](https://python-all.ru/3/library/signal.html#signal.SIGILL). Также их можно включить при запуске, установив переменную окружения [`PYTHONFAULTHANDLER`](https://python-all.ru/3/using/cmdline.html#envvar-PYTHONFAULTHANDLER) или используя параметр командной строки [`-X`](https://python-all.ru/3/using/cmdline.html#cmdoption-X) `faulthandler`.1415Обработчик сбоев совместим с системными обработчиками сбоев, такими как Apport или обработчик сбоев Windows. Модуль использует альтернативный стек для обработчиков сигналов, если доступна функция `sigaltstack()`. Это позволяет выполнять дамп трассировки даже при переполнении стека.1617Обработчик сбоев вызывается в катастрофических ситуациях и поэтому может использовать только сигналобезопасные функции (например, не может выделять память в куче). Из-за этого ограничения дамп трассировки является минимальным по сравнению с обычными трассировками Python:1819- Поддерживается только ASCII. При кодировании используется обработчик ошибок `backslashreplace`.20- Каждая строка ограничена 500 символами.21- Отображаются только имя файла, имя функции и номер строки (исходный код не показывается).22- Ограничение – 100 фреймов и 100 потоков.23- Порядок обратный: сначала показывается самый последний вызов.2425По умолчанию трассировка Python записывается в [`sys.stderr`](https://python-all.ru/3/library/sys.html#sys.stderr). Чтобы увидеть трассировки, приложения должны запускаться в терминале. Вместо этого можно передать файл журнала в [`faulthandler.enable()`](https://python-all.ru/3/library/faulthandler.html#faulthandler.enable).2627Модуль реализован на C, поэтому трассировки могут быть выгружены при сбое или при взаимоблокировке Python.2829Режим [разработки Python](https://python-all.ru/3/library/devmode.html#devmode) вызывает [`faulthandler.enable()`](https://python-all.ru/3/library/faulthandler.html#faulthandler.enable) при запуске Python.3031> **См. также**32>33> **Модуль [`pdb`](https://python-all.ru/3/library/pdb.html#module-pdb)**34>35> Интерактивный отладчик исходного кода для программ на Python.36>37> **Модуль [`traceback`](https://python-all.ru/3/library/traceback.html#module-traceback)**38>39> Стандартный интерфейс для извлечения, форматирования и вывода трассировок стека программ на Python.4041## Дамп трассировки4243#### `faulthandler.dump_traceback(file=sys.stderr, all_threads=True)`4445Выгружает трассировки всех потоков в *file*. Если *all\_threads* равно `False`, выгружает только текущий поток.4647> **См. также**48>49> [`traceback.print_tb()`](https://python-all.ru/3/library/traceback.html#traceback.print_tb), который можно использовать для вывода объекта трассировки.5051Изменено в версии 3.5: Добавлена поддержка передачи файлового дескриптора в эту функцию.5253## Дамп C-стека5455Добавлено в версии 3.14.5657#### `faulthandler.dump_c_stack(file=sys.stderr)`5859Выгружает трассировку C-стека текущего потока в *file*.6061Если сборка Python не поддерживает это или операционная система не предоставляет трассировку стека, то вместо дампа C-стека выводится сообщение об ошибке.6263### Совместимость C-стека6465Если система не поддерживает *[backtrace(3)](https://python-all.ru/3/library/faulthandler.html)* или *[dladdr1(3)](https://python-all.ru/3/library/faulthandler.html)* на уровне C, то дампы C-стека работать не будут. Вместо стека будет выведена ошибка.6667Кроме того, некоторые компиляторы не поддерживают реализацию дампов C-стека [CPython](https://python-all.ru/3/glossary.html#term-CPython). В результате вместо стека может быть выведена другая ошибка, даже если операционная система поддерживает дампы стеков.6869> **Примечание**70>71> Дампы C-стеков могут быть сколь угодно медленными в зависимости от уровня DWARF бинарных файлов в стеке вызовов.7273## Состояние обработчика сбоев7475#### `faulthandler.enable(file=sys.stderr, all_threads=True, c_stack=True)`7677Включает обработчик сбоев: устанавливает обработчики для сигналов [`SIGSEGV`](https://python-all.ru/3/library/signal.html#signal.SIGSEGV), [`SIGFPE`](https://python-all.ru/3/library/signal.html#signal.SIGFPE), [`SIGABRT`](https://python-all.ru/3/library/signal.html#signal.SIGABRT), [`SIGBUS`](https://python-all.ru/3/library/signal.html#signal.SIGBUS) и [`SIGILL`](https://python-all.ru/3/library/signal.html#signal.SIGILL) для дампа трассировки Python. Если *all\_threads* равно `True`, создаются трассировки для всех работающих потоков. В противном случае выполняется дамп только текущего потока.7879Файл *file* должен оставаться открытым, пока обработчик сбоев не отключён: см. [проблему с файловыми дескрипторами](https://python-all.ru/3/library/faulthandler.html#faulthandler-fd).8081Если *c\_stack* равен `True`, то стек C выводится после трассировки Python, если только система это не поддерживает. Дополнительную информацию о совместимости см. в [`dump_c_stack()`](https://python-all.ru/3/library/faulthandler.html#faulthandler.dump_c_stack).8283Изменено в версии 3.5: Добавлена поддержка передачи файлового дескриптора в эту функцию.8485Изменено в версии 3.6: В Windows также устанавливается обработчик для исключений Windows.8687Изменено в версии 3.10: В дампе теперь указывается, выполняется ли сборка мусора, если *all\_threads* равен true.8889Изменено в версии 3.14: Если [GIL](https://python-all.ru/3/glossary.html#term-GIL) отключён, дампится только текущий поток, чтобы избежать риска состояния гонки.9091Изменено в версии 3.14: Теперь в дампе отображается стек C, если *c\_stack* равен true.9293#### `faulthandler.disable()`9495Отключает обработчик ошибок: удаляет обработчики сигналов, установленные вызовом [`enable()`](https://python-all.ru/3/library/faulthandler.html#faulthandler.enable).9697#### `faulthandler.is_enabled()`9899Проверяет, включён ли обработчик ошибок.100101## Дамп трассировок по истечении тайм-аута102103#### `faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)`104105Выводит трассировки всех потоков по истечении тайм-аута *timeout* секунд или каждые *timeout* секунд, если *repeat* равен `True`. Если *exit* равен `True`, вызывает `_exit()` с кодом завершения 1 после вывода трассировок. (Обратите внимание, что `_exit()` завершает процесс немедленно, не выполняя никакой очистки, например, сброса буферов файлов.) Если функция вызывается дважды, новый вызов заменяет предыдущие параметры и сбрасывает таймер. Таймер имеет субсекундное разрешение.106107Файл *file* должен оставаться открытым до тех пор, пока не будет выведена трассировка или не будет вызвана [`cancel_dump_traceback_later()`](https://python-all.ru/3/library/faulthandler.html#faulthandler.cancel_dump_traceback_later): см. [проблему с файловыми дескрипторами](https://python-all.ru/3/library/faulthandler.html#faulthandler-fd).108109Эта функция реализована с использованием потока-наблюдателя.110111Изменено в версии 3.5: Добавлена поддержка передачи файлового дескриптора в эту функцию.112113Изменено в версии 3.7: Эта функция теперь всегда доступна.114115#### `faulthandler.cancel_dump_traceback_later()`116117Отменяет последний вызов [`dump_traceback_later()`](https://python-all.ru/3/library/faulthandler.html#faulthandler.dump_traceback_later).118119## Дамп трассировки по сигналу пользователя120121#### `faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)`122123Register 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`.124125Файл *file* должен оставаться открытым до тех пор, пока сигнал не будет отменён вызовом [`unregister()`](https://python-all.ru/3/library/faulthandler.html#faulthandler.unregister): см. [проблему с файловыми дескрипторами](https://python-all.ru/3/library/faulthandler.html#faulthandler-fd).126127Недоступно в Windows.128129Изменено в версии 3.5: Добавлена поддержка передачи файлового дескриптора в эту функцию.130131#### `faulthandler.unregister(signum)`132133Отменяет регистрацию сигнала пользователя: удаляет обработчик сигнала *signum*, установленный вызовом [`register()`](https://python-all.ru/3/library/faulthandler.html#faulthandler.register). Возвращает `True`, если сигнал был зарегистрирован, иначе `False`.134135Недоступно в Windows.136137## Проблема с файловыми дескрипторами138139[`enable()`](https://python-all.ru/3/library/faulthandler.html#faulthandler.enable), [`dump_traceback_later()`](https://python-all.ru/3/library/faulthandler.html#faulthandler.dump_traceback_later) и [`register()`](https://python-all.ru/3/library/faulthandler.html#faulthandler.register) сохраняют файловый дескриптор своего аргумента *file*. Если файл закрывается и его файловый дескриптор используется повторно новым файлом, или если для замены файлового дескриптора используется [`os.dup2()`](https://python-all.ru/3/library/os.html#os.dup2), трассировка будет записана в другой файл. Вызывайте эти функции снова каждый раз при замене файла.140141## Пример142143Пример ошибки сегментации в Linux при включённом и выключенном обработчике ошибок:144145```console146$ python -c "import ctypes; ctypes.string_at(0)"147Segmentation fault148149$ python -q -X faulthandler150>>> import ctypes151>>> ctypes.string_at(0)152Fatal Python error: Segmentation fault153154Current thread 0x00007fb899f39700 (most recent call first):155  File "/opt/python/Lib/ctypes/__init__.py", line 486 in string_at156  File "<stdin>", line 1 in <module>157158Current thread's C stack trace (most recent call first):159  Binary file "/opt/python/python", at _Py_DumpStack+0x42 [0x5b27f7d7147e]160  Binary file "/opt/python/python", at +0x32dcbd [0x5b27f7d85cbd]161  Binary file "/opt/python/python", at +0x32df8a [0x5b27f7d85f8a]162  Binary file "/usr/lib/libc.so.6", at +0x3def0 [0x77b73226bef0]163  Binary file "/usr/lib/libc.so.6", at +0x17ef9c [0x77b7323acf9c]164  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0xcdf6 [0x77b7315dddf6]165  Binary file "/usr/lib/libffi.so.8", at +0x7976 [0x77b73158f976]166  Binary file "/usr/lib/libffi.so.8", at +0x413c [0x77b73158c13c]167  Binary file "/usr/lib/libffi.so.8", at ffi_call+0x12e [0x77b73158ef0e]168  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x15a33 [0x77b7315e6a33]169  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x164fa [0x77b7315e74fa]170  Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0xc624 [0x77b7315dd624]171  Binary file "/opt/python/python", at _PyObject_MakeTpCall+0xce [0x5b27f7b73883]172  Binary file "/opt/python/python", at +0x11bab6 [0x5b27f7b73ab6]173  Binary file "/opt/python/python", at PyObject_Vectorcall+0x23 [0x5b27f7b73b04]174  Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x490c [0x5b27f7cbb302]175  Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]176  Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]177  Binary file "/opt/python/python", at PyEval_EvalCode+0xc5 [0x5b27f7cd9ba3]178  Binary file "/opt/python/python", at +0x255957 [0x5b27f7cad957]179  Binary file "/opt/python/python", at +0x255ab4 [0x5b27f7cadab4]180  Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x6c3e [0x5b27f7cbd634]181  Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]182  Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]183  Binary file "/opt/python/python", at +0x11b6e1 [0x5b27f7b736e1]184  Binary file "/opt/python/python", at +0x11d348 [0x5b27f7b75348]185  Binary file "/opt/python/python", at +0x11d626 [0x5b27f7b75626]186  Binary file "/opt/python/python", at PyObject_Call+0x20 [0x5b27f7b7565e]187  Binary file "/opt/python/python", at +0x32a67a [0x5b27f7d8267a]188  Binary file "/opt/python/python", at +0x32a7f8 [0x5b27f7d827f8]189  Binary file "/opt/python/python", at +0x32ac1b [0x5b27f7d82c1b]190  Binary file "/opt/python/python", at Py_RunMain+0x31 [0x5b27f7d82ebe]191  <truncated rest of calls>192Segmentation fault193```194