`faulthandler.md`

133 строк · 12.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.13/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.13/library/faulthandler.html#faulthandler.enable) устанавливает обработчики сбоев для сигналов [`SIGSEGV`](https://python-all.ru/3.13/library/signal.html#signal.SIGSEGV), [`SIGFPE`](https://python-all.ru/3.13/library/signal.html#signal.SIGFPE), [`SIGABRT`](https://python-all.ru/3.13/library/signal.html#signal.SIGABRT), [`SIGBUS`](https://python-all.ru/3.13/library/signal.html#signal.SIGBUS) и [`SIGILL`](https://python-all.ru/3.13/library/signal.html#signal.SIGILL). Также их можно включить при запуске, установив переменную окружения [`PYTHONFAULTHANDLER`](https://python-all.ru/3.13/using/cmdline.html#envvar-PYTHONFAULTHANDLER) или используя параметр командной строки [`-X`](https://python-all.ru/3.13/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.13/library/sys.html#sys.stderr). Чтобы увидеть трассировки, приложения должны запускаться в терминале. Вместо этого можно передать файл журнала в [`faulthandler.enable()`](https://python-all.ru/3.13/library/faulthandler.html#faulthandler.enable).2627Модуль реализован на C, поэтому трассировки могут быть выгружены при сбое или при взаимоблокировке Python.2829Режим [разработки Python](https://python-all.ru/3.13/library/devmode.html#devmode) вызывает [`faulthandler.enable()`](https://python-all.ru/3.13/library/faulthandler.html#faulthandler.enable) при запуске Python.3031> **См. также**32>33> **Модуль [`pdb`](https://python-all.ru/3.13/library/pdb.html#module-pdb)**34>35> Интерактивный отладчик исходного кода для программ на Python.36>37> **Модуль [`traceback`](https://python-all.ru/3.13/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.13/library/traceback.html#traceback.print_tb), который можно использовать для вывода объекта трассировки.5051Изменено в версии 3.5: Добавлена поддержка передачи файлового дескриптора в эту функцию.5253## Состояние обработчика сбоев5455#### `faulthandler.enable(file=sys.stderr, all_threads=True)`5657Включает обработчик сбоев: устанавливает обработчики для сигналов [`SIGSEGV`](https://python-all.ru/3.13/library/signal.html#signal.SIGSEGV), [`SIGFPE`](https://python-all.ru/3.13/library/signal.html#signal.SIGFPE), [`SIGABRT`](https://python-all.ru/3.13/library/signal.html#signal.SIGABRT), [`SIGBUS`](https://python-all.ru/3.13/library/signal.html#signal.SIGBUS) и [`SIGILL`](https://python-all.ru/3.13/library/signal.html#signal.SIGILL) для дампа трассировки Python. Если *all\_threads* равно `True`, создаются трассировки для всех работающих потоков. В противном случае выполняется дамп только текущего потока.5859Файл *file* должен оставаться открытым, пока обработчик сбоев не отключён: см. [проблему с файловыми дескрипторами](https://python-all.ru/3.13/library/faulthandler.html#faulthandler-fd).6061Изменено в версии 3.5: Добавлена поддержка передачи файлового дескриптора в эту функцию.6263Изменено в версии 3.6: В Windows также устанавливается обработчик для исключений Windows.6465Изменено в версии 3.10: В дампе теперь указывается, выполняется ли сборка мусора, если *all\_threads* равен true.6667#### `faulthandler.disable()`6869Отключает обработчик ошибок: удаляет обработчики сигналов, установленные вызовом [`enable()`](https://python-all.ru/3.13/library/faulthandler.html#faulthandler.enable).7071#### `faulthandler.is_enabled()`7273Проверяет, включён ли обработчик ошибок.7475## Дамп трассировок по истечении тайм-аута7677#### `faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)`7879Выводит трассировки всех потоков по истечении тайм-аута *timeout* секунд или каждые *timeout* секунд, если *repeat* равен `True`. Если *exit* равен `True`, вызывает `_exit()` с кодом завершения 1 после вывода трассировок. (Обратите внимание, что `_exit()` завершает процесс немедленно, не выполняя никакой очистки, например, сброса буферов файлов.) Если функция вызывается дважды, новый вызов заменяет предыдущие параметры и сбрасывает таймер. Таймер имеет субсекундное разрешение.8081Файл *file* должен оставаться открытым до тех пор, пока не будет выведена трассировка или не будет вызвана [`cancel_dump_traceback_later()`](https://python-all.ru/3.13/library/faulthandler.html#faulthandler.cancel_dump_traceback_later): см. [проблему с файловыми дескрипторами](https://python-all.ru/3.13/library/faulthandler.html#faulthandler-fd).8283Эта функция реализована с использованием потока-наблюдателя.8485Изменено в версии 3.5: Добавлена поддержка передачи файлового дескриптора в эту функцию.8687Изменено в версии 3.7: Эта функция теперь всегда доступна.8889#### `faulthandler.cancel_dump_traceback_later()`9091Отменяет последний вызов [`dump_traceback_later()`](https://python-all.ru/3.13/library/faulthandler.html#faulthandler.dump_traceback_later).9293## Дамп трассировки по сигналу пользователя9495#### `faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)`9697Register 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`.9899Файл *file* должен оставаться открытым до тех пор, пока сигнал не будет отменён вызовом [`unregister()`](https://python-all.ru/3.13/library/faulthandler.html#faulthandler.unregister): см. [проблему с файловыми дескрипторами](https://python-all.ru/3.13/library/faulthandler.html#faulthandler-fd).100101Недоступно в Windows.102103Изменено в версии 3.5: Добавлена поддержка передачи файлового дескриптора в эту функцию.104105#### `faulthandler.unregister(signum)`106107Отменяет регистрацию сигнала пользователя: удаляет обработчик сигнала *signum*, установленный вызовом [`register()`](https://python-all.ru/3.13/library/faulthandler.html#faulthandler.register). Возвращает `True`, если сигнал был зарегистрирован, иначе `False`.108109Недоступно в Windows.110111## Проблема с файловыми дескрипторами112113[`enable()`](https://python-all.ru/3.13/library/faulthandler.html#faulthandler.enable), [`dump_traceback_later()`](https://python-all.ru/3.13/library/faulthandler.html#faulthandler.dump_traceback_later) и [`register()`](https://python-all.ru/3.13/library/faulthandler.html#faulthandler.register) сохраняют файловый дескриптор своего аргумента *file*. Если файл закрывается и его файловый дескриптор используется повторно новым файлом, или если для замены файлового дескриптора используется [`os.dup2()`](https://python-all.ru/3.13/library/os.html#os.dup2), трассировка будет записана в другой файл. Вызывайте эти функции снова каждый раз при замене файла.114115## Пример116117Пример ошибки сегментации в Linux при включённом и выключенном обработчике ошибок:118119```console120$ python -c "import ctypes; ctypes.string_at(0)"121Segmentation fault122123$ python -q -X faulthandler124>>> import ctypes125>>> ctypes.string_at(0)126Fatal Python error: Segmentation fault127128Current thread 0x00007fb899f39700 (most recent call first):129  File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at130  File "<stdin>", line 1 in <module>131Segmentation fault132```133