Debian Codegraph @

Doc/library/sys.monitoring.rst

raw
1 :mod:`!sys.monitoring` --- Execution event monitoring
2 =====================================================
3
4 .. module:: sys.monitoring
5 :synopsis: Access and control event monitoring
6
7 .. versionadded:: 3.12
8
9 -----------------
10
11 .. note::
12
13 :mod:`!sys.monitoring` is a namespace within the :mod:`sys` module,
14 not an independent module, and ``import sys.monitoring`` would fail
15 with a :exc:`ModuleNotFoundError`. Instead, simply ``import sys``
16 and then use ``sys.monitoring``.
17
18
19 This namespace provides access to the functions and constants necessary to
20 activate and control event monitoring.
21
22 As programs execute, events occur that might be of interest to tools that
23 monitor execution. The :mod:`sys.monitoring` namespace provides means to
24 receive callbacks when events of interest occur.
25
26 The monitoring API consists of three components:
27
28 * `Tool identifiers`_
29 * `Events`_
30 * :ref:`Callbacks <callbacks>`
31
32 Tool identifiers
33 ----------------
34
35 A tool identifier is an integer and the associated name.
36 Tool identifiers are used to discourage tools from interfering with each
37 other and to allow multiple tools to operate at the same time.
38 Currently tools are completely independent and cannot be used to
39 monitor each other. This restriction may be lifted in the future.
40
41 Before registering or activating events, a tool should choose an identifier.
42 Identifiers are integers in the range 0 to 5 inclusive.
43
44 Registering and using tools
45 '''''''''''''''''''''''''''
46
47 .. function:: use_tool_id(tool_id: int, name: str, /) -> None
48
49 Must be called before *tool_id* can be used.
50 *tool_id* must be in the range 0 to 5 inclusive.
51 Raises a :exc:`ValueError` if *tool_id* is in use.
52
53 .. function:: free_tool_id(tool_id: int, /) -> None
54
55 Should be called once a tool no longer requires *tool_id*.
56
57 .. note::
58
59 :func:`free_tool_id` will not disable global or local events associated
60 with *tool_id*, nor will it unregister any callback functions. This
61 function is only intended to be used to notify the VM that the
62 particular *tool_id* is no longer in use.
63
64 .. function:: get_tool(tool_id: int, /) -> str | None
65
66 Returns the name of the tool if *tool_id* is in use,
67 otherwise it returns ``None``.
68 *tool_id* must be in the range 0 to 5 inclusive.
69
70 All IDs are treated the same by the VM with regard to events, but the
71 following IDs are pre-defined to make co-operation of tools easier::
72
73 sys.monitoring.DEBUGGER_ID = 0
74 sys.monitoring.COVERAGE_ID = 1
75 sys.monitoring.PROFILER_ID = 2
76 sys.monitoring.OPTIMIZER_ID = 5
77
78
79 Events
80 ------
81
82 The following events are supported:
83
84 .. monitoring-event:: BRANCH
85
86 A conditional branch is taken (or not).
87
88 .. monitoring-event:: CALL
89
90 A call in Python code (event occurs before the call).
91
92 .. monitoring-event:: C_RAISE
93
94 An exception raised from any callable, except for Python functions (event occurs after the exit).
95
96 .. monitoring-event:: C_RETURN
97
98 Return from any callable, except for Python functions (event occurs after the return).
99
100 .. monitoring-event:: EXCEPTION_HANDLED
101
102 An exception is handled.
103
104 .. monitoring-event:: INSTRUCTION
105
106 A VM instruction is about to be executed.
107
108 .. monitoring-event:: JUMP
109
110 An unconditional jump in the control flow graph is made.
111
112 .. monitoring-event:: LINE
113
114 An instruction is about to be executed that has a different line number from the preceding instruction.
115
116 .. monitoring-event:: PY_RESUME
117
118 Resumption of a Python function (for generator and coroutine functions), except for ``throw()`` calls.
119
120 .. monitoring-event:: PY_RETURN
121
122 Return from a Python function (occurs immediately before the return, the callee's frame will be on the stack).
123
124 .. monitoring-event:: PY_START
125
126 Start of a Python function (occurs immediately after the call, the callee's frame will be on the stack)
127
128 .. monitoring-event:: PY_THROW
129
130 A Python function is resumed by a ``throw()`` call.
131
132 .. monitoring-event:: PY_UNWIND
133
134 Exit from a Python function during exception unwinding.
135
136 .. monitoring-event:: PY_YIELD
137
138 Yield from a Python function (occurs immediately before the yield, the callee's frame will be on the stack).
139
140 .. monitoring-event:: RAISE
141
142 An exception is raised, except those that cause a :monitoring-event:`STOP_ITERATION` event.
143
144 .. monitoring-event:: RERAISE
145
146 An exception is re-raised, for example at the end of a :keyword:`finally` block.
147
148 .. monitoring-event:: STOP_ITERATION
149
150 An artificial :exc:`StopIteration` is raised; see `the STOP_ITERATION event`_.
151
152
153 More events may be added in the future.
154
155 These events are attributes of the :mod:`!sys.monitoring.events` namespace.
156 Each event is represented as a power-of-2 integer constant.
157 To define a set of events, simply bitwise OR the individual events together.
158 For example, to specify both :monitoring-event:`PY_RETURN` and :monitoring-event:`PY_START`
159 events, use the expression ``PY_RETURN | PY_START``.
160
161 .. monitoring-event:: NO_EVENTS
162
163 An alias for ``0`` so users can do explicit comparisons like::
164
165 if get_events(DEBUGGER_ID) == NO_EVENTS:
166 ...
167
168 Events are divided into three groups:
169
170 .. _monitoring-event-local:
171
172 Local events
173 ''''''''''''
174
175 Local events are associated with normal execution of the program and happen
176 at clearly defined locations. All local events can be disabled.
177 The local events are:
178
179 * :monitoring-event:`PY_START`
180 * :monitoring-event:`PY_RESUME`
181 * :monitoring-event:`PY_RETURN`
182 * :monitoring-event:`PY_YIELD`
183 * :monitoring-event:`CALL`
184 * :monitoring-event:`LINE`
185 * :monitoring-event:`INSTRUCTION`
186 * :monitoring-event:`JUMP`
187 * :monitoring-event:`BRANCH`
188 * :monitoring-event:`STOP_ITERATION`
189
190 Ancillary events
191 ''''''''''''''''
192
193 Ancillary events can be monitored like other events, but are controlled
194 by another event:
195
196 * :monitoring-event:`C_RAISE`
197 * :monitoring-event:`C_RETURN`
198
199 The :monitoring-event:`C_RETURN` and :monitoring-event:`C_RAISE` events
200 are controlled by the :monitoring-event:`CALL` event.
201 :monitoring-event:`C_RETURN` and :monitoring-event:`C_RAISE` events will only be
202 seen if the corresponding :monitoring-event:`CALL` event is being monitored.
203
204
205 .. _monitoring-event-global:
206
207 Other events
208 ''''''''''''
209
210 Other events are not necessarily tied to a specific location in the
211 program and cannot be individually disabled via :data:`DISABLE`.
212
213 The other events that can be monitored are:
214
215 * :monitoring-event:`PY_THROW`
216 * :monitoring-event:`PY_UNWIND`
217 * :monitoring-event:`RAISE`
218 * :monitoring-event:`EXCEPTION_HANDLED`
219
220
221 The STOP_ITERATION event
222 ''''''''''''''''''''''''
223
224 :pep:`PEP 380 <380#use-of-stopiteration-to-return-values>`
225 specifies that a :exc:`StopIteration` exception is raised when returning a value
226 from a generator or coroutine. However, this is a very inefficient way to
227 return a value, so some Python implementations, notably CPython 3.12+, do not
228 raise an exception unless it would be visible to other code.
229
230 To allow tools to monitor for real exceptions without slowing down generators
231 and coroutines, the :monitoring-event:`STOP_ITERATION` event is provided.
232 :monitoring-event:`STOP_ITERATION` can be locally disabled, unlike :monitoring-event:`RAISE`.
233
234
235 Turning events on and off
236 -------------------------
237
238 In order to monitor an event, it must be turned on and a corresponding callback
239 must be registered.
240 Events can be turned on or off by setting the events either globally or
241 for a particular code object.
242
243
244 Setting events globally
245 '''''''''''''''''''''''
246
247 Events can be controlled globally by modifying the set of events being monitored.
248
249 .. function:: get_events(tool_id: int, /) -> int
250
251 Returns the ``int`` representing all the active events.
252
253 .. function:: set_events(tool_id: int, event_set: int, /) -> None
254
255 Activates all events which are set in *event_set*.
256 Raises a :exc:`ValueError` if *tool_id* is not in use.
257
258 No events are active by default.
259
260 Per code object events
261 ''''''''''''''''''''''
262
263 Events can also be controlled on a per code object basis. The functions
264 defined below which accept a :class:`types.CodeType` should be prepared
265 to accept a look-alike object from functions which are not defined
266 in Python (see :ref:`c-api-monitoring`).
267
268 .. function:: get_local_events(tool_id: int, code: CodeType, /) -> int
269
270 Returns all the :ref:`local events <monitoring-event-local>` for *code*
271
272 .. function:: set_local_events(tool_id: int, code: CodeType, event_set: int, /) -> None
273
274 Activates all the :ref:`local events <monitoring-event-local>` for *code*
275 which are set in *event_set*. Raises a :exc:`ValueError` if *tool_id* is not
276 in use.
277
278 Local events add to global events, but do not mask them.
279 In other words, all global events will trigger for a code object,
280 regardless of the local events.
281
282
283 Disabling events
284 ''''''''''''''''
285
286 .. data:: DISABLE
287
288 A special value that can be returned from a callback function to disable
289 events for the current code location.
290
291 :ref:`Local events <monitoring-event-local>` can be disabled for a specific code
292 location by returning :data:`sys.monitoring.DISABLE` from a callback function.
293 This does not change which events are set, or any other code locations for the
294 same event.
295
296 Disabling events for specific locations is very important for high
297 performance monitoring. For example, a program can be run under a
298 debugger with no overhead if the debugger disables all monitoring
299 except for a few breakpoints.
300
301 If :data:`DISABLE` is returned by a callback for a
302 :ref:`global event <monitoring-event-global>`, :exc:`ValueError` will be raised
303 by the interpreter in a non-specific location (that is, no traceback will be
304 provided).
305
306 .. function:: restart_events() -> None
307
308 Enable all the events that were disabled by :data:`sys.monitoring.DISABLE`
309 for all tools.
310
311
312 .. _callbacks:
313
314 Registering callback functions
315 ------------------------------
316
317 To register a callable for events call
318
319 .. function:: register_callback(tool_id: int, event: int, func: Callable | None, /) -> Callable | None
320
321 Registers the callable *func* for the *event* with the given *tool_id*
322
323 If another callback was registered for the given *tool_id* and *event*,
324 it is unregistered and returned.
325 Otherwise :func:`register_callback` returns ``None``.
326
327 .. audit-event:: sys.monitoring.register_callback func sys.monitoring.register_callback
328
329 Functions can be unregistered by calling
330 ``sys.monitoring.register_callback(tool_id, event, None)``.
331
332 Callback functions can be registered and unregistered at any time.
333
334
335 Callback function arguments
336 '''''''''''''''''''''''''''
337
338 .. data:: MISSING
339
340 A special value that is passed to a callback function to indicate
341 that there are no arguments to the call.
342
343 When an active event occurs, the registered callback function is called.
344 Different events will provide the callback function with different arguments, as follows:
345
346 * :monitoring-event:`PY_START` and :monitoring-event:`PY_RESUME`::
347
348 func(code: CodeType, instruction_offset: int) -> DISABLE | Any
349
350 * :monitoring-event:`PY_RETURN` and :monitoring-event:`PY_YIELD`::
351
352 func(code: CodeType, instruction_offset: int, retval: object) -> DISABLE | Any
353
354 * :monitoring-event:`CALL`, :monitoring-event:`C_RAISE` and :monitoring-event:`C_RETURN`::
355
356 func(code: CodeType, instruction_offset: int, callable: object, arg0: object | MISSING) -> DISABLE | Any
357
358 If there are no arguments, *arg0* is set to :data:`sys.monitoring.MISSING`.
359
360 * :monitoring-event:`RAISE`, :monitoring-event:`RERAISE`, :monitoring-event:`EXCEPTION_HANDLED`,
361 :monitoring-event:`PY_UNWIND`, :monitoring-event:`PY_THROW` and :monitoring-event:`STOP_ITERATION`::
362
363 func(code: CodeType, instruction_offset: int, exception: BaseException) -> DISABLE | Any
364
365 * :monitoring-event:`LINE`::
366
367 func(code: CodeType, line_number: int) -> DISABLE | Any
368
369 * :monitoring-event:`BRANCH` and :monitoring-event:`JUMP`::
370
371 func(code: CodeType, instruction_offset: int, destination_offset: int) -> DISABLE | Any
372
373 Note that the *destination_offset* is where the code will next execute.
374 For an untaken branch this will be the offset of the instruction following
375 the branch.
376
377 * :monitoring-event:`INSTRUCTION`::
378
379 func(code: CodeType, instruction_offset: int) -> DISABLE | Any