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 не используется.

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

События для каждого объекта кода

События также можно контролировать для каждого объекта кода.

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