`faulthandler.md`

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