What three sys.monitoring calls must you make before an event callback fires?

`sys.monitoring` is CPython's instrumentation API, introduced in 3.12 by PEP 669 and extended in 3.14. It exists so that debuggers, coverage recorders and profilers can be told *exactly* which runtime events they care about, and so the interpreter can compile instrumentation into only the code that is actually being watched. Getting events out of it is a fixed three-step handshake, and every step exists for a reason. ### Step one — claim a tool id ```python import sys sys.monitoring.use_tool_id(sys.monitoring.PROFILER_ID, "call-logger") ``` Instrumentation state in CPython is partitioned into **six independent slots**, numbered 0 through 5. Each slot is a *tool*: its own callbacks, its own subscribed event set, its own per-location disable state. Two tools can watch the same event in the same function without seeing each other's callbacks — which is the whole point, because a coverage recorder and a debugger routinely run in the same process. `sys.monitoring.use_tool_id(tool_id, name)` claims a slot and gives it a human-readable name. It raises `ValueError` if that slot is already in use (`tool 3 is already in use`) and also if the id is out of range (`invalid tool 6 (must be between 0 and 5)`). `sys.monitoring.get_tool(tool_id)` returns the registered name of whoever holds a slot, or `None` if it is free — call it before claiming if you want a graceful message rather than an exception. Four module-level constants name the conventional slots: `sys.monitoring.DEBUGGER_ID` (0), `sys.monitoring.COVERAGE_ID` (1), `sys.monitoring.PROFILER_ID` (2) and `sys.monitoring.OPTIMIZER_ID` (5). These are conventions, not enforcement — nothing stops a coverage tool from taking id 4 — but honouring them keeps unrelated tools out of each other's way. `sys.monitoring.free_tool_id(tool_id)` releases the slot. It is not automatic; a library that claims an id and never frees it holds one of six process-wide slots for the life of the interpreter. ### Step two — register a callback ```python sys.monitoring.register_callback( sys.monitoring.PROFILER_ID, sys.monitoring.events.PY_START, on_py_start ) ``` `register_callback(tool_id, event, func)` attaches one function to **one** event for one tool. It returns whatever callback was registered before — `None` on the first call — so a wrapper can chain to the previous handler or restore it afterwards. Passing `None` as the function unregisters. The callback signature is determined by the event, not by you. A `sys.monitoring.events.PY_START` handler receives `(code, instruction_offset)`; a `sys.monitoring.events.LINE` handler receives `(code, line_number)`; a `sys.monitoring.events.CALL` handler receives `(code, instruction_offset, callable, arg0)`, where `arg0` is the sentinel `sys.monitoring.MISSING` when the call has no first argument. Getting the arity wrong surfaces as a `TypeError` raised from inside the interpreter at the first event, which is a confusing place to debug, so check the signature for each event you subscribe. ### Step three — turn the events on ```python sys.monitoring.set_events( sys.monitoring.PROFILER_ID, sys.monitoring.events.PY_START ) ``` `set_events(tool_id, event_set)` is the switch. The argument is a **bit set**: the constants in the `sys.monitoring.events` namespace are integers you combine with `|`, and `sys.monitoring.events.NO_EVENTS` (zero) turns everything off for that tool. `sys.monitoring.get_events(tool_id)` reads the current set back. Note that `set_events` *replaces* the set rather than adding to it — to add an event, OR it into the value you read from `get_events`. Two failure modes matter here. Calling `set_events` for a slot you never claimed raises `ValueError: tool 4 is not in use` — this is the mistake that catches people who register a callback and expect it to work. And `sys.monitoring.events.C_RETURN` and `sys.monitoring.events.C_RAISE` cannot be enabled on their own; the interpreter raises `ValueError: cannot set C_RETURN or C_RAISE events independently`, because they are only tracked alongside `sys.monitoring.events.CALL`. ### What is *not* an error Enabling an event with no callback registered is silently fine — the event is tracked and nothing is delivered. Registering a callback without enabling the event is also fine, and equally silent. That symmetry is why "nothing happens" is the classic first bug with this API: the three calls are independent, and only all three together produce a callback. ### Teardown The disciplined shape is `set_events(tool_id, sys.monitoring.events.NO_EVENTS)` followed by `free_tool_id(tool_id)`, ideally in a `finally`. `sys.monitoring.clear_tool_id(tool_id)` is the shortcut that unregisters the callbacks and clears the events for a tool in one call while keeping the slot claimed. Leaving instrumentation armed after a diagnostic run means the process keeps paying for callbacks nobody reads. ### Why the handshake is shaped this way The three-step design is not ceremony. Because a tool declares its identity first, CPython can keep one instrumentation state per slot and decide, per code object and per instruction, which tools need a callback there — that is what lets a coverage recorder and a debugger coexist without either one seeing the other's events or paying for them. Because the subscription is a separate, explicit bit set rather than a single always-on hook, the interpreter knows the exact list of events to compile in, and can leave everything else running as ordinary bytecode. The practical consequence for you is a debugging checklist when no callbacks arrive. Confirm the slot is claimed (`sys.monitoring.get_tool` returns your name, not `None`). Confirm the event you registered is the same constant you enabled — subscribing to `sys.monitoring.events.CALL` and registering for `sys.monitoring.events.PY_START` is a silent mismatch. Confirm the enabled set is what you think it is by reading it back with `sys.monitoring.get_events`, remembering that `set_events` replaces rather than adds. And confirm the callback's arity matches the event, because a wrong signature surfaces as a `TypeError` raised from deep inside the interpreter rather than at the line you wrote.