faulthandler — Вывод отладочной информации при ошибках 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.

1. Вывод отладочной информации

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

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

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

2. Состояние обработчика ошибок

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

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

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

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

faulthandler.disable()

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

faulthandler.is_enabled()

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

3. Вывод отладочной информации после таймаута

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

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

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

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

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

faulthandler.cancel_dump_traceback_later()

Отменяет последний вызов dump_traceback_later().

4. Вывод отладочной информации при пользовательском сигнале

faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)

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

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

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

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

faulthandler.unregister(signum)

Отменяет регистрацию пользовательского сигнала: удаляет обработчик сигнала signum, установленный функцией register(). Возвращает True, если сигнал был зарегистрирован, и False, в противном случае.

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

5. Проблемы с дескрипторами файлов

enable(), dump_traceback_later() и register() сохраняют дескриптор файла их аргумента file. Если файл закрыт, а его дескриптор повторно используется новым файлом, или если os.dup2() используется для замены дескриптора файла, отладочная информация будет записана в другой файл. Вызывайте эти функции каждый раз, когда файл заменяется.

6. Пример

Пример сегментации памяти на Linux с включенным и выключенным обработчиком ошибок:

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

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

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