faulthandler — Dump the Python traceback

Нове в версії 3.3.

This module contains functions to dump Python tracebacks explicitly, on a fault, after a timeout, or on a user signal. Call faulthandler.enable() to install fault handlers for the SIGSEGV, SIGFPE, SIGABRT, SIGBUS, and SIGILL signals. You can also enable them at startup by setting the PYTHONFAULTHANDLER environment variable or by using the -X faulthandler command line option.

The fault handler is compatible with system fault handlers like Apport or the Windows fault handler. The module uses an alternative stack for signal handlers if the sigaltstack() function is available. This allows it to dump the traceback even on a stack overflow.

Обробник помилок викликається в катастрофічних випадках і тому може використовувати лише безпечні для сигналу функції (наприклад, він не може виділяти пам’ять у купі). Через це обмеження дамп зворотного відстеження мінімальний порівняно зі звичайним відстеженням Python:

  • Підтримується лише ASCII. Під час кодування використовується обробник помилок backslashreplace.

  • Довжина кожного рядка обмежена 500 символами.

  • Відображаються лише назва файлу, назва функції та номер рядка. (без вихідного коду)

  • Він обмежений 100 кадрами та 100 потоками.

  • Порядок зворотний: останній виклик відображається першим.

За замовчуванням відстеження Python записується в sys.stderr. Щоб побачити відстеження, програми мають бути запущені в терміналі. Файл журналу також можна передати до faulthandler.enable().

Модуль реалізовано на C, тому трасування можна скинути під час збою або коли Python заблоковано.

Режим розробки Python викликає faulthandler.enable() під час запуску Python.

Викидання трасування

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

Дамп трасування всіх потоків у файл. Якщо all_threads має значення False, створювати дамп лише поточного потоку.

Змінено в версії 3.5: Додано підтримку для передачі дескриптора файлу в цю функцію.

Стан обробника помилок

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

Enable the fault handler: install handlers for the SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL signals to dump the Python traceback. If all_threads is True, produce tracebacks for every running thread. Otherwise, dump only the current thread.

Файл має бути відкритим, доки обробник помилок не буде вимкнено: див. проблему з дескрипторами файлів.

Змінено в версії 3.5: Додано підтримку для передачі дескриптора файлу в цю функцію.

Змінено в версії 3.6: У Windows також встановлено обробник винятків Windows.

faulthandler.disable()

Вимкніть обробник помилок: видаліть обробники сигналів, встановлені enable().

faulthandler.is_enabled()

Перевірте, чи ввімкнено обробник помилок.

Викидання трасування після тайм-ауту

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

Dump the tracebacks of all threads, after a timeout of timeout seconds, or every timeout seconds if repeat is True. If exit is True, call _exit() with status=1 after dumping the tracebacks. (Note _exit() exits the process immediately, which means it doesn’t do any cleanup like flushing file buffers.) If the function is called twice, the new call replaces previous parameters and resets the timeout. The timer has a sub-second resolution.

Файл має залишатися відкритим, доки не буде створено дамп трасування або cancel_dump_traceback_later(): див. проблему з дескрипторами файлів.

Ця функція реалізована за допомогою сторожового потоку.

Змінено в версії 3.7: Тепер ця функція доступна завжди.

Змінено в версії 3.5: Додано підтримку для передачі дескриптора файлу в цю функцію.

faulthandler.cancel_dump_traceback_later()

Скасувати останній виклик dump_traceback_later().

Скидання зворотного відстеження за сигналом користувача

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

Зареєструйте сигнал користувача: встановіть обробник для сигналу signum, щоб скинути зворотне трасування всіх потоків або поточного потоку, якщо all_threads має значення False, у файл. Викликати попередній обробник, якщо ланцюжок має значення True.

Файл має залишатися відкритим, доки сигнал не буде скасовано unregister(): див. проблему з дескрипторами файлів.

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

Змінено в версії 3.5: Додано підтримку для передачі дескриптора файлу в цю функцію.

faulthandler.unregister(signum)

Скасувати реєстрацію сигналу користувача: видалити обробник сигналу signum, встановлений register(). Повертає True, якщо сигнал був зареєстрований, False інакше.

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

Проблема з дескрипторами файлів

enable(), dump_traceback_later() і register() зберігають файловий дескриптор свого аргументу file. Якщо файл закрито і його файловий дескриптор повторно використовується в новому файлі, або якщо os.dup2() використовується для заміни файлового дескриптора, трасування буде записане в інший файл. Викликайте ці функції знову щоразу, коли файл замінюється.

приклад

Приклад помилки сегментації в 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