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:: clear_tool_id(tool_id: int, /) -> None
54
55 Unregister all events and callback functions associated with *tool_id*.
56
57 .. function:: free_tool_id(tool_id: int, /) -> None
58
59 Should be called once a tool no longer requires *tool_id*.
60 Will call :func:`clear_tool_id` before releasing *tool_id*.
61
62 .. function:: get_tool(tool_id: int, /) -> str | None
63
64 Returns the name of the tool if *tool_id* is in use,
65 otherwise it returns ``None``.
66 *tool_id* must be in the range 0 to 5 inclusive.
67
68 All IDs are treated the same by the VM with regard to events, but the
69 following IDs are pre-defined to make co-operation of tools easier::
70
71 sys.monitoring.DEBUGGER_ID = 0
72 sys.monitoring.COVERAGE_ID = 1
73 sys.monitoring.PROFILER_ID = 2
74 sys.monitoring.OPTIMIZER_ID = 5
75
76
77 Events
78 ------
79
80 The following events are supported:
81
82 .. monitoring-event:: BRANCH_LEFT
83
84 A conditional branch goes left.
85
86 It is up to the tool to determine how to present "left" and "right" branches.
87 There is no guarantee which branch is "left" and which is "right", except
88 that it will be consistent for the duration of the program.
89
90 .. monitoring-event:: BRANCH_RIGHT
91
92 A conditional branch goes right.
93
94 .. monitoring-event:: CALL
95
96 A call in Python code (event occurs before the call).
97
98 .. monitoring-event:: C_RAISE
99
100 An exception raised from any callable, except for Python functions (event occurs after the exit).
101
102 .. monitoring-event:: C_RETURN
103
104 Return from any callable, except for Python functions (event occurs after the return).
105
106 .. monitoring-event:: EXCEPTION_HANDLED
107
108 An exception is handled.
109
110 .. monitoring-event:: INSTRUCTION
111
112 A VM instruction is about to be executed.
113
114 .. monitoring-event:: JUMP
115
116 An unconditional jump in the control flow graph is made.
117
118 .. monitoring-event:: LINE
119
120 An instruction is about to be executed that has a different line number from the preceding instruction.
121
122 .. monitoring-event:: PY_RESUME
123
124 Resumption of a Python function (for generator and coroutine functions), except for ``throw()`` calls.
125
126 .. monitoring-event:: PY_RETURN
127
128 Return from a Python function (occurs immediately before the return, the callee's frame will be on the stack).
129
130 .. monitoring-event:: PY_START
131
132 Start of a Python function (occurs immediately after the call, the callee's frame will be on the stack)
133
134 .. monitoring-event:: PY_THROW
135
136 A Python function is resumed by a ``throw()`` call.
137
138 .. monitoring-event:: PY_UNWIND
139
140 Exit from a Python function during exception unwinding. This includes exceptions raised directly within the
141 function and that are allowed to continue to propagate.
142
143 .. monitoring-event:: PY_YIELD
144
145 Yield from a Python function (occurs immediately before the yield, the callee's frame will be on the stack).
146
147 .. monitoring-event:: RAISE
148
149 An exception is raised, except those that cause a :monitoring-event:`STOP_ITERATION` event.
150
151 .. monitoring-event:: RERAISE
152
153 An exception is re-raised, for example at the end of a :keyword:`finally` block.
154
155 .. monitoring-event:: STOP_ITERATION
156
157 An artificial :exc:`StopIteration` is raised; see `the STOP_ITERATION event`_.
158
159
160 More events may be added in the future.
161
162 These events are attributes of the :mod:`!sys.monitoring.events` namespace.
163 Each event is represented as a power-of-2 integer constant.
164 To define a set of events, simply bitwise OR the individual events together.
165 For example, to specify both :monitoring-event:`PY_RETURN` and :monitoring-event:`PY_START`
166 events, use the expression ``PY_RETURN | PY_START``.
167
168 .. monitoring-event:: NO_EVENTS
169
170 An alias for ``0`` so users can do explicit comparisons like::
171
172 if get_events(DEBUGGER_ID) == NO_EVENTS:
173 ...
174
175 Setting this event deactivates all events.
176
177 .. _monitoring-event-local:
178
179 Local events
180 ''''''''''''
181
182 Local events are associated with normal execution of the program and happen
183 at clearly defined locations. All local events can be disabled.
184 The local events are:
185
186 * :monitoring-event:`PY_START`
187 * :monitoring-event:`PY_RESUME`
188 * :monitoring-event:`PY_RETURN`
189 * :monitoring-event:`PY_YIELD`
190 * :monitoring-event:`CALL`
191 * :monitoring-event:`LINE`
192 * :monitoring-event:`INSTRUCTION`
193 * :monitoring-event:`JUMP`
194 * :monitoring-event:`BRANCH_LEFT`
195 * :monitoring-event:`BRANCH_RIGHT`
196 * :monitoring-event:`STOP_ITERATION`
197
198 Deprecated event
199 ''''''''''''''''
200
201 * ``BRANCH``
202
203 The ``BRANCH`` event is deprecated in 3.14.
204 Using :monitoring-event:`BRANCH_LEFT` and :monitoring-event:`BRANCH_RIGHT`
205 events will give much better performance as they can be disabled
206 independently.
207
208 Ancillary events
209 ''''''''''''''''
210
211 Ancillary events can be monitored like other events, but are controlled
212 by another event:
213
214 * :monitoring-event:`C_RAISE`
215 * :monitoring-event:`C_RETURN`
216
217 The :monitoring-event:`C_RETURN` and :monitoring-event:`C_RAISE` events
218 are controlled by the :monitoring-event:`CALL` event.
219 :monitoring-event:`C_RETURN` and :monitoring-event:`C_RAISE` events will only be
220 seen if the corresponding :monitoring-event:`CALL` event is being monitored.
221
222
223 .. _monitoring-event-global:
224
225 Other events
226 ''''''''''''
227
228 Other events are not necessarily tied to a specific location in the
229 program and cannot be individually disabled via :data:`DISABLE`.
230
231 The other events that can be monitored are:
232
233 * :monitoring-event:`PY_THROW`
234 * :monitoring-event:`PY_UNWIND`
235 * :monitoring-event:`RAISE`
236 * :monitoring-event:`EXCEPTION_HANDLED`
237
238
239 The STOP_ITERATION event
240 ''''''''''''''''''''''''
241
242 :pep:`PEP 380 <380#use-of-stopiteration-to-return-values>`
243 specifies that a :exc:`StopIteration` exception is raised when returning a value
244 from a generator or coroutine. However, this is a very inefficient way to
245 return a value, so some Python implementations, notably CPython 3.12+, do not
246 raise an exception unless it would be visible to other code.
247
248 To allow tools to monitor for real exceptions without slowing down generators
249 and coroutines, the :monitoring-event:`STOP_ITERATION` event is provided.
250 :monitoring-event:`STOP_ITERATION` can be locally disabled, unlike
251 :monitoring-event:`RAISE`.
252
253 Note that the :monitoring-event:`STOP_ITERATION` event and the
254 :monitoring-event:`RAISE` event for a :exc:`StopIteration` exception are
255 equivalent, and are treated as interchangeable when generating events.
256 Implementations will favor :monitoring-event:`STOP_ITERATION` for performance
257 reasons, but may generate a :monitoring-event:`RAISE` event with a
258 :exc:`StopIteration`.
259
260 Turning events on and off
261 -------------------------
262
263 In order to monitor an event, it must be turned on and a corresponding callback
264 must be registered. Events can be turned on or off by setting the events either
265 globally and/or for a particular code object. An event will trigger only once,
266 even if it is turned on both globally and locally.
267
268
269 Setting events globally
270 '''''''''''''''''''''''
271
272 Events can be controlled globally by modifying the set of events being monitored.
273
274 .. function:: get_events(tool_id: int, /) -> int
275
276 Returns the ``int`` representing all the active events.
277
278 .. function:: set_events(tool_id: int, event_set: int, /) -> None
279
280 Activates all events which are set in *event_set*.
281 Raises a :exc:`ValueError` if *tool_id* is not in use.
282
283 No events are active by default.
284
285 Per code object events
286 ''''''''''''''''''''''
287
288 Events can also be controlled on a per code object basis. The functions
289 defined below which accept a :class:`types.CodeType` should be prepared
290 to accept a look-alike object from functions which are not defined
291 in Python (see :ref:`c-api-monitoring`).
292
293 .. function:: get_local_events(tool_id: int, code: CodeType, /) -> int
294
295 Returns all the :ref:`local events <monitoring-event-local>` for *code*
296
297 .. function:: set_local_events(tool_id: int, code: CodeType, event_set: int, /) -> None
298
299 Activates all the :ref:`local events <monitoring-event-local>` for *code*
300 which are set in *event_set*. Raises a :exc:`ValueError` if *tool_id* is not
301 in use.
302
303
304 Disabling events
305 ''''''''''''''''
306
307 .. data:: DISABLE
308
309 A special value that can be returned from a callback function to disable
310 events for the current code location.
311
312 :ref:`Local events <monitoring-event-local>` can be disabled for a specific code
313 location by returning :data:`sys.monitoring.DISABLE` from a callback function.
314 This does not change which events are set, or any other code locations for the
315 same event.
316
317 Disabling events for specific locations is very important for high
318 performance monitoring. For example, a program can be run under a
319 debugger with no overhead if the debugger disables all monitoring
320 except for a few breakpoints.
321
322 If :data:`DISABLE` is returned by a callback for a
323 :ref:`global event <monitoring-event-global>`, :exc:`ValueError` will be raised
324 by the interpreter in a non-specific location (that is, no traceback will be
325 provided).
326
327 .. function:: restart_events() -> None
328
329 Enable all the events that were disabled by :data:`sys.monitoring.DISABLE`
330 for all tools.
331
332
333 .. _callbacks:
334
335 Registering callback functions
336 ------------------------------
337
338 .. function:: register_callback(tool_id: int, event: int, func: Callable | None, /) -> Callable | None
339
340 Registers the callable *func* for the *event* with the given *tool_id*
341
342 If another callback was registered for the given *tool_id* and *event*,
343 it is unregistered and returned.
344 Otherwise :func:`register_callback` returns ``None``.
345
346 .. audit-event:: sys.monitoring.register_callback func sys.monitoring.register_callback
347
348 Functions can be unregistered by calling
349 ``sys.monitoring.register_callback(tool_id, event, None)``.
350
351 Callback functions can be registered and unregistered at any time.
352
353 Callbacks are called only once regardless if the event is turned on both
354 globally and locally. As such, if an event could be turned on for both global
355 and local events by your code then the callback needs to be written to handle
356 either trigger.
357
358
359 Callback function arguments
360 '''''''''''''''''''''''''''
361
362 .. data:: MISSING
363
364 A special value that is passed to a callback function to indicate
365 that there are no arguments to the call.
366
367 When an active event occurs, the registered callback function is called.
368 Callback functions returning an object other than :data:`DISABLE` will have no effect.
369 Different events will provide the callback function with different arguments, as follows:
370
371 * :monitoring-event:`PY_START` and :monitoring-event:`PY_RESUME`::
372
373 func(code: CodeType, instruction_offset: int) -> object
374
375 * :monitoring-event:`PY_RETURN` and :monitoring-event:`PY_YIELD`::
376
377 func(code: CodeType, instruction_offset: int, retval: object) -> object
378
379 * :monitoring-event:`CALL`, :monitoring-event:`C_RAISE` and :monitoring-event:`C_RETURN`
380 (*arg0* can be :data:`MISSING` specifically)::
381
382 func(code: CodeType, instruction_offset: int, callable: object, arg0: object) -> object
383
384 *code* represents the code object where the call is being made, while
385 *callable* is the object that is about to be called (and thus
386 triggered the event).
387 If there are no arguments, *arg0* is set to :data:`sys.monitoring.MISSING`.
388
389 For instance methods, *callable* will be the function object as found on the
390 class with *arg0* set to the instance (i.e. the ``self`` argument to the
391 method).
392
393 * :monitoring-event:`RAISE`, :monitoring-event:`RERAISE`, :monitoring-event:`EXCEPTION_HANDLED`,
394 :monitoring-event:`PY_UNWIND`, :monitoring-event:`PY_THROW` and :monitoring-event:`STOP_ITERATION`::
395
396 func(code: CodeType, instruction_offset: int, exception: BaseException) -> object
397
398 * :monitoring-event:`LINE`::
399
400 func(code: CodeType, line_number: int) -> object
401
402 * :monitoring-event:`BRANCH_LEFT`, :monitoring-event:`BRANCH_RIGHT` and :monitoring-event:`JUMP`::
403
404 func(code: CodeType, instruction_offset: int, destination_offset: int) -> object
405
406 Note that the *destination_offset* is where the code will next execute.
407
408 * :monitoring-event:`INSTRUCTION`::
409
410 func(code: CodeType, instruction_offset: int) -> object