sys.monitoring — Мониторинг событий выполнения

Регистрация и использование инструментов

sys.monitoring.use_tool_id(tool_id: int, name: str, /) → None

Эту функцию необходимо вызвать, прежде чем можно будет использовать tool_id. Значение tool_id должно находиться в диапазоне от 0 до 5 включительно. Вызывает исключение ValueError, если tool_id уже используется.

sys.monitoring.clear_tool_id(tool_id: int, /) → None

Отменяет регистрацию всех событий и функций обратного вызова, связанных с tool_id.

sys.monitoring.free_tool_id(tool_id: int, /) → None

Эту функцию следует вызвать, когда инструменту больше не требуется tool_id. Перед освобождением tool_id будет вызвана функция clear_tool_id().

sys.monitoring.get_tool(tool_id: int, /) → str | None

Возвращает имя инструмента, если tool_id используется, иначе возвращает None. Значение tool_id должно находиться в диапазоне от 0 до 5 включительно.

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

sys.monitoring.DEBUGGER_ID = 0
sys.monitoring.COVERAGE_ID = 1
sys.monitoring.PROFILER_ID = 2
sys.monitoring.OPTIMIZER_ID = 5

Локальные события

Локальные события связаны с обычным выполнением программы и происходят в чётко определённых местах. Все локальные события можно отключить. К локальным событиям относятся:

• PY_START
• PY_RESUME
• PY_RETURN
• PY_YIELD
• CALL
• LINE
• INSTRUCTION
• JUMP
• BRANCH_LEFT
• BRANCH_RIGHT
• STOP_ITERATION

Устаревшее событие

• BRANCH

Событие BRANCH устарело начиная с версии 3.14. Использование событий BRANCH_LEFT и BRANCH_RIGHT обеспечивает значительно более высокую производительность, поскольку их можно отключать независимо друг от друга.

Вспомогательные события

Вспомогательные события можно отслеживать так же, как и другие события, но управляются они другим событием:

• C_RAISE
• C_RETURN

События C_RETURN и C_RAISE управляются событием CALL. События C_RETURN и C_RAISE будут видны только в том случае, если отслеживается соответствующее событие CALL.

Другие события

Другие события не обязательно связаны с конкретным местом в программе, и их нельзя отключить по отдельности с помощью DISABLE.

К другим событиям, которые можно отслеживать, относятся:

• PY_THROW
• PY_UNWIND
• RAISE
• EXCEPTION_HANDLED

Событие STOP_ITERATION

PEP 380 устанавливает, что при возврате значения из генератора или сопрограммы вызывается исключение StopIteration. Однако это очень неэффективный способ возврата значения, поэтому некоторые реализации Python, в частности CPython 3.12+, не вызывают исключение, если оно не будет видимым для другого кода.

Чтобы инструменты могли отслеживать настоящие исключения, не замедляя генераторы и сопрограммы, предусмотрено событие STOP_ITERATION. STOP_ITERATION можно отключить локально, в отличие от RAISE.

Обратите внимание: событие STOP_ITERATION и событие RAISE для исключения StopIteration эквивалентны и при генерации событий считаются взаимозаменяемыми. По соображениям производительности реализации будут отдавать предпочтение STOP_ITERATION, но могут генерировать событие RAISE с помощью StopIteration.

Глобальная настройка событий

Событиями можно управлять глобально, изменяя набор отслеживаемых событий.

sys.monitoring.get_events(tool_id: int, /) → int

Возвращает int, представляющий все активные события.

sys.monitoring.set_events(tool_id: int, event_set: int, /) → None

Активирует все события, заданные в event_set. Вызывает исключение ValueError, если tool_id не используется.

По умолчанию события не активны.

События для отдельных объектов кода

Событиями также можно управлять отдельно для каждого объекта кода. Функции, определённые ниже и принимающие types.CodeType, должны быть готовы принимать объект, подобный ему, от функций, определённых не на Python (см. API мониторинга C).

sys.monitoring.get_local_events(tool_id: int, code: CodeType, /) → int

Возвращает все локальные события для code.

sys.monitoring.set_local_events(tool_id: int, code: CodeType, event_set: int, /) → None

Активирует все локальные события для code, заданные в event_set. Вызывает исключение ValueError, если tool_id не используется.

Отключение событий

sys.monitoring.DISABLE

Специальное значение, которое можно вернуть из функции обратного вызова, чтобы отключить события для текущего местоположения в коде.

Локальные события можно отключить для конкретного местоположения в коде, вернув из функции обратного вызова sys.monitoring.DISABLE. Это не изменяет набор включённых событий и не влияет на другие местоположения для того же события.

Отключение событий для конкретных местоположений очень важно для высокопроизводительного мониторинга. Например, программу можно запустить в отладчике без накладных расходов, если отладчик отключит мониторинг везде, кроме нескольких точек останова.

Если функция обратного вызова для глобального события возвращает DISABLE, интерпретатор вызовет исключение ValueError в неопределённом месте (то есть трассировка стека предоставлена не будет).

sys.monitoring.restart_events() → None

Включает все события, отключённые с помощью sys.monitoring.DISABLE для всех инструментов.

Аргументы функций обратного вызова

sys.monitoring.MISSING

Специальное значение, передаваемое функции обратного вызова, чтобы указать, что у вызова нет аргументов.

При возникновении активного события вызывается зарегистрированная функция обратного вызова. Возвращаемый ею объект не влияет на результат, если это не DISABLE. Разные события передают функции обратного вызова разные аргументы:

• PY_START и PY_RESUME:

  func(code: CodeType, instruction_offset: int) -> object
  

• PY_RETURN и PY_YIELD:

  func(code: CodeType, instruction_offset: int, retval: object) -> object
  

• CALL, C_RAISE и C_RETURN (в частности, arg0 может быть равен MISSING):

  func(code: CodeType, instruction_offset: int, callable: object, arg0: object) -> object
  

  code — это объект кода, в котором выполняется вызов, а callable — объект, который собираются вызвать (и который, таким образом, вызвал событие). Если аргументов нет, arg0 присваивается значение sys.monitoring.MISSING.

  Для методов экземпляра callable будет объектом функции, найденным в классе, а arg0 будет содержать экземпляр (то есть аргумент self метода).

• RAISE, RERAISE, EXCEPTION_HANDLED, PY_UNWIND, PY_THROW и STOP_ITERATION:

  func(code: CodeType, instruction_offset: int, exception: BaseException) -> object
  

• LINE:

  func(code: CodeType, line_number: int) -> object
  

• BRANCH_LEFT, BRANCH_RIGHT и JUMP:

  func(code: CodeType, instruction_offset: int, destination_offset: int) -> object
  

  Обратите внимание: destination_offset — это место, где будет выполнена следующая инструкция кода.

• INSTRUCTION:

  func(code: CodeType, instruction_offset: int) -> object