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

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

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

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

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

Должна быть вызвана, когда инструмент больше не требует 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
• STOP_ITERATION

Дополнительные события

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

• C_RAISE
• C_RETURN

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

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

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

Другие отслеживаемые события:

• PY_THROW
• PY_UNWIND
• RAISE
• EXCEPTION_HANDLED

Событие STOP_ITERATION

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

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

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

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

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 из функции обратного вызова. Это не изменяет какие события установлены или любые другие расположения кода для того же события.

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

sys.monitoring.restart_events() → None

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

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

sys.monitoring.MISSING

Особое значение, которое передаётся функции обратного вызова для обозначения отсутствия аргументов вызова.

При возникновении активного события зарегистрированная функция обратного вызова вызывается. Разные события обеспечат функцию обратного вызова различными аргументами, как показано ниже:

• PY_START и PY_RESUME:

  func(code: CodeType, instruction_offset: int) -> DISABLE | Any
  

• PY_RETURN и PY_YIELD:

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

• CALL, C_RAISE и C_RETURN:

  func(code: CodeType, instruction_offset: int, callable: object, arg0: object | MISSING) -> DISABLE | Any
  

  Если аргументов нет, arg0 устанавливается в sys.monitoring.MISSING.

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

  func(code: CodeType, instruction_offset: int, exception: BaseException) -> DISABLE | Any
  

• LINE:

  func(code: CodeType, line_number: int) -> DISABLE | Any
  

• BRANCH и JUMP:

  func(code: CodeType, instruction_offset: int, destination_offset: int) -> DISABLE | Any
  

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

• INSTRUCTION:

  func(code: CodeType, instruction_offset: int) -> DISABLE | Any