`sys.monitoring.md`

299 строк · 22.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.12/library/sys.monitoring.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `sys.monitoring` – Мониторинг событий выполнения89Добавлено в версии 3.12.1011---1213> **Примечание**14>15> [`sys.monitoring`](https://python-all.ru/3.12/library/sys.monitoring.html#module-sys.monitoring) является пространством имён внутри модуля [`sys`](https://python-all.ru/3.12/library/sys.html#module-sys), не независимым модулем, поэтому нет необходимости `import sys.monitoring`, просто `import sys`, а затем использовать `sys.monitoring`.1617Это пространство имён предоставляет доступ к функциям и константам, необходимым для активации и управления мониторингом событий.1819В процессе выполнения программ возникают события, которые могут представлять интерес для инструментов, отслеживающих выполнение. Пространство имён [`sys.monitoring`](https://python-all.ru/3.12/library/sys.monitoring.html#module-sys.monitoring) предоставляет средства для получения колбэков при возникновении интересующих событий.2021API мониторинга состоит из трёх компонентов:2223- [Идентификаторы инструментов](https://python-all.ru/3.12/library/sys.monitoring.html#tool-identifiers)24- [События](https://python-all.ru/3.12/library/sys.monitoring.html#events)25- [Колбэки](https://python-all.ru/3.12/library/sys.monitoring.html#callbacks)2627## Идентификаторы инструментов2829Идентификатор инструмента – это целое число и связанное с ним имя. Идентификаторы инструментов используются для предотвращения взаимного вмешательства инструментов и для возможности одновременной работы нескольких инструментов. В настоящее время инструменты полностью независимы и не могут использоваться для мониторинга друг друга. В будущем это ограничение может быть снято.3031Перед регистрацией или активацией событий инструмент должен выбрать идентификатор. Идентификаторы – целые числа в диапазоне от 0 до 5 включительно.3233### Регистрация и использование инструментов3435#### `sys.monitoring.use_tool_id(tool_id: int, name: str, /) → None`3637Должен быть вызван до того, как *tool\_id* можно будет использовать. *tool\_id* должен находиться в диапазоне от 0 до 5 включительно. Вызывает исключение [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError), если *tool\_id* уже используется.3839#### `sys.monitoring.free_tool_id(tool_id: int, /) → None`4041Должна вызываться, когда инструмент больше не требует *tool\_id*.4243> **Примечание**44>45> [`free_tool_id()`](https://python-all.ru/3.12/library/sys.monitoring.html#sys.monitoring.free_tool_id) не отключает глобальные или локальные события, связанные с *tool\_id*, а также не отменяет регистрацию каких-либо функций обратного вызова. Эта функция предназначена только для уведомления виртуальной машины о том, что конкретный *tool\_id* больше не используется.4647#### `sys.monitoring.get_tool(tool_id: int, /) → str | None`4849Возвращает имя инструмента, если *tool\_id* используется, в противном случае возвращает `None`. *tool\_id* должен находиться в диапазоне от 0 до 5 включительно.5051Все идентификаторы обрабатываются виртуальной машиной одинаково с точки зрения событий, но следующие идентификаторы предопределены для упрощения совместной работы инструментов:5253```python54sys.monitoring.DEBUGGER_ID = 055sys.monitoring.COVERAGE_ID = 156sys.monitoring.PROFILER_ID = 257sys.monitoring.OPTIMIZER_ID = 558```5960Нет обязательства устанавливать идентификатор, и ничто не мешает инструменту использовать идентификатор, даже если он уже используется. Однако рекомендуется, чтобы инструменты использовали уникальный идентификатор и уважали другие инструменты.6162## События6364Поддерживаются следующие события:6566#### `sys.monitoring.events.BRANCH`6768Условный переход выполняется (или нет).6970#### `sys.monitoring.events.CALL`7172Вызов в коде Python (событие происходит до вызова).7374#### `sys.monitoring.events.C_RAISE`7576Исключение, возбуждённое любым вызываемым объектом, за исключением функций Python (событие происходит после выхода).7778#### `sys.monitoring.events.C_RETURN`7980Возврат из любого вызываемого объекта, кроме функций Python (событие происходит после возврата).8182#### `sys.monitoring.events.EXCEPTION_HANDLED`8384Исключение обработано.8586#### `sys.monitoring.events.INSTRUCTION`8788Инструкция виртуальной машины будет выполнена.8990#### `sys.monitoring.events.JUMP`9192Выполняется безусловный переход в графе потока управления.9394#### `sys.monitoring.events.LINE`9596Инструкция, номер строки которой отличается от номера строки предыдущей инструкции, будет выполнена.9798#### `sys.monitoring.events.PY_RESUME`99100Возобновление функции Python (для функций-генераторов и корутинных функций), за исключением вызовов `throw()`.101102#### `sys.monitoring.events.PY_RETURN`103104Возврат из функции Python (происходит непосредственно перед возвратом, фрейм вызываемой функции будет находиться в стеке).105106#### `sys.monitoring.events.PY_START`107108Начало функции Python (происходит сразу после вызова, фрейм вызываемой функции будет находиться в стеке).109110#### `sys.monitoring.events.PY_THROW`111112Функция Python возобновляется вызовом `throw()`.113114#### `sys.monitoring.events.PY_UNWIND`115116Выход из функции Python во время раскрутки стека исключений.117118#### `sys.monitoring.events.PY_YIELD`119120Yield из функции Python (происходит непосредственно перед yield, фрейм вызываемой функции будет находиться в стеке).121122#### `sys.monitoring.events.RAISE`123124Исключение возбуждается, за исключением тех, которые приводят к событию [`STOP_ITERATION`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-STOP_ITERATION).125126#### `sys.monitoring.events.RERAISE`127128Исключение возбуждается повторно, например, в конце блока [`finally`](https://python-all.ru/3.12/reference/compound_stmts.html#finally).129130#### `sys.monitoring.events.STOP_ITERATION`131132Возбуждается искусственное [`StopIteration`](https://python-all.ru/3.12/library/exceptions.html#StopIteration); см. [событие STOP\_ITERATION](https://python-all.ru/3.12/library/sys.monitoring.html#the-stop-iteration-event).133134В будущем могут быть добавлены новые события.135136Эти события являются атрибутами пространства имён `sys.monitoring.events`. Каждое событие представлено целочисленной константой, являющейся степенью двойки. Чтобы определить набор событий, просто выполните побитовое ИЛИ отдельных событий. Например, чтобы задать и [`PY_RETURN`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_RETURN), и [`PY_START`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_START) события, используйте выражение `PY_RETURN | PY_START`.137138#### `sys.monitoring.events.NO_EVENTS`139140Псевдоним для `0`, чтобы пользователи могли выполнять явные сравнения, например:141142```python143if get_events(DEBUGGER_ID) == NO_EVENTS:144    ...145```146147События разделены на три группы:148149### Локальные события150151Локальные события связаны с обычным выполнением программы и происходят в четко определенных местах. Все локальные события можно отключить. Локальные события:152153- [`PY_START`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_START)154- [`PY_RESUME`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_RESUME)155- [`PY_RETURN`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_RETURN)156- [`PY_YIELD`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_YIELD)157- [`CALL`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-CALL)158- [`LINE`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-LINE)159- [`INSTRUCTION`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-INSTRUCTION)160- [`JUMP`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-JUMP)161- [`BRANCH`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-BRANCH)162- [`STOP_ITERATION`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-STOP_ITERATION)163164### Вспомогательные события165166Вспомогательные события можно отслеживать, как и другие, но они управляются другим событием:167168- [`C_RAISE`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-C_RAISE)169- [`C_RETURN`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-C_RETURN)170171События [`C_RETURN`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-C_RETURN) и [`C_RAISE`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-C_RAISE) управляются событием [`CALL`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-CALL). События [`C_RETURN`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-C_RETURN) и [`C_RAISE`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-C_RAISE) будут видны только в том случае, если соответствующее событие [`CALL`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-CALL) отслеживается.172173### Прочие события174175Другие события не обязательно привязаны к конкретному месту в программе и не могут быть отключены по отдельности.176177Прочие события, которые можно отслеживать:178179- [`PY_THROW`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_THROW)180- [`PY_UNWIND`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_UNWIND)181- [`RAISE`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-RAISE)182- [`EXCEPTION_HANDLED`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-EXCEPTION_HANDLED)183184### Событие STOP\_ITERATION185186[**PEP 380**](https://python-all.ru/3.12/library/sys.monitoring.html) указывает, что при возврате значения из генератора или корутины возбуждается исключение [`StopIteration`](https://python-all.ru/3.12/library/exceptions.html#StopIteration). Однако это очень неэффективный способ возврата значения, поэтому некоторые реализации Python, в частности CPython 3.12+, не возбуждают исключение, если оно не будет видно другому коду.187188Чтобы инструменты могли отслеживать реальные исключения, не замедляя работу генераторов и корутин, предоставляется событие [`STOP_ITERATION`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-STOP_ITERATION). [`STOP_ITERATION`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-STOP_ITERATION) можно отключать локально, в отличие от [`RAISE`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-RAISE).189190## Включение и отключение событий191192Чтобы отслеживать событие, его необходимо включить и зарегистрировать соответствующий колбэк. События можно включать или отключать, задавая их глобально или для конкретного объекта кода.193194### Глобальная настройка событий195196События можно контролировать глобально, изменяя набор отслеживаемых событий.197198#### `sys.monitoring.get_events(tool_id: int, /) → int`199200Возвращает `int`, представляющую все активные события.201202#### `sys.monitoring.set_events(tool_id: int, event_set: int, /) → None`203204Активирует все события, установленные в *event\_set*. Возбуждает [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError), если *tool\_id* не используется.205206По умолчанию ни одно событие не активно.207208### События для каждого объекта кода209210События также можно контролировать для каждого объекта кода отдельно.211212#### `sys.monitoring.get_local_events(tool_id: int, code: CodeType, /) → int`213214Возвращает все локальные события для *code*215216#### `sys.monitoring.set_local_events(tool_id: int, code: CodeType, event_set: int, /) → None`217218Активирует все локальные события для *code*, установленные в *event\_set*. Возбуждает [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError), если *tool\_id* не используется.219220Локальные события добавляются к глобальным, но не скрывают их. Иными словами, все глобальные события срабатывают для объекта кода независимо от локальных событий.221222### Отключение событий223224#### `sys.monitoring.DISABLE`225226Специальное значение, которое можно вернуть из функции обратного вызова, чтобы отключить события для текущего местоположения в коде.227228Локальные события можно отключить для конкретного участка кода, вернув [`sys.monitoring.DISABLE`](https://python-all.ru/3.12/library/sys.monitoring.html#sys.monitoring.DISABLE) из функции обратного вызова. Это не изменяет набор установленных событий и не затрагивает другие участки кода для того же события.229230Отключение событий для конкретных мест очень важно для высокопроизводительного мониторинга. Например, программу можно запускать под отладчиком без накладных расходов, если отладчик отключает весь мониторинг, кроме нескольких точек останова.231232#### `sys.monitoring.restart_events() → None`233234Включить все события, которые были отключены вызовом [`sys.monitoring.DISABLE`](https://python-all.ru/3.12/library/sys.monitoring.html#sys.monitoring.DISABLE) для всех инструментов.235236## Регистрация функций обратного вызова237238Чтобы зарегистрировать вызываемый объект для событий, вызовите239240#### `sys.monitoring.register_callback(tool_id: int, event: int, func: Callable | None, /) → Callable | None`241242Регистрирует вызываемый объект *func* для события *event* с заданным *tool\_id*243244Если для заданных *tool\_id* и *event* был зарегистрирован другой обратный вызов, он отменяется и возвращается. В противном случае [`register_callback()`](https://python-all.ru/3.12/library/sys.monitoring.html#sys.monitoring.register_callback) возвращает `None`.245246Функции можно отменить, вызвав `sys.monitoring.register_callback(tool_id, event, None)`.247248Функции обратного вызова можно регистрировать и отменять в любое время.249250Регистрация или удаление функции обратного вызова генерирует событие [`sys.audit()`](https://python-all.ru/3.12/library/sys.html#sys.audit).251252### Аргументы функции обратного вызова253254#### `sys.monitoring.MISSING`255256Специальное значение, которое передаётся функции обратного вызова, чтобы указать, что у вызова нет аргументов.257258Когда происходит активное событие, вызывается зарегистрированный колбэк. Разные события передают колбэку различные аргументы, как показано ниже:259260- [`PY_START`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_START) и [`PY_RESUME`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_RESUME):261262  ```python263  func(code: CodeType, instruction_offset: int) -> DISABLE | Any264  ```265- [`PY_RETURN`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_RETURN) и [`PY_YIELD`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_YIELD):266267  ```python268  func(code: CodeType, instruction_offset: int, retval: object) -> DISABLE | Any269  ```270- [`CALL`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-CALL), [`C_RAISE`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-C_RAISE) и [`C_RETURN`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-C_RETURN):271272  ```python273  func(code: CodeType, instruction_offset: int, callable: object, arg0: object | MISSING) -> DISABLE | Any274  ```275276  Если аргументы отсутствуют, *arg0* устанавливается в [`sys.monitoring.MISSING`](https://python-all.ru/3.12/library/sys.monitoring.html#sys.monitoring.MISSING).277- [`RAISE`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-RAISE), [`RERAISE`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-RERAISE), [`EXCEPTION_HANDLED`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-EXCEPTION_HANDLED), [`PY_UNWIND`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_UNWIND), [`PY_THROW`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-PY_THROW) и [`STOP_ITERATION`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-STOP_ITERATION):278279  ```python280  func(code: CodeType, instruction_offset: int, exception: BaseException) -> DISABLE | Any281  ```282- [`LINE`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-LINE):283284  ```python285  func(code: CodeType, line_number: int) -> DISABLE | Any286  ```287- [`BRANCH`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-BRANCH) и [`JUMP`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-JUMP):288289  ```python290  func(code: CodeType, instruction_offset: int, destination_offset: int) -> DISABLE | Any291  ```292293  Обратите внимание, что *destination\_offset* – это смещение, по которому код будет выполняться далее. Для невыбранной ветки это будет смещение инструкции, следующей за веткой.294- [`INSTRUCTION`](https://python-all.ru/3.12/library/sys.monitoring.html#monitoring-event-INSTRUCTION):295296  ```python297  func(code: CodeType, instruction_offset: int) -> DISABLE | Any298  ```299