chore: wrapping context support for Python 3.15

[P403n1x87]

Description

We add support for the wrapping context for 3.15 by leveraging the low-impact monitoring API. With the latest, changes the API now allows making all events local per-code object, so this allows us to set local exception unwinding events to catch per-function thrown exceptions.

[cit-pr-commenter-54b7da]

Codeowners resolved as

ddtrace/internal/wrapping/asyncs.py                                     @DataDog/apm-core-python

[datadog-datadog-prod-us1]

 

✨ Unblock PR with BitsAI

⚠️ Warnings

🚦 49 Pipeline jobs failed

DataDog/apm-reliability/dd-trace-py | appsec/appsec 3/4     

DataDog/apm-reliability/dd-trace-py | ci_visibility/testing 13/21     

DataDog/apm-reliability/dd-trace-py | ci_visibility/testing 21/21     

View all 49 failed jobs.

ℹ️ Info

No other issues found (see more)

🧪 All tests passed
❄️ No new flaky tests detected

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: c369b05 | Docs | Datadog PR Page | Give us feedback!}

[pr-commenter]

Benchmarks

Benchmark execution time: 2026-07-18 04:29:11

Comparing candidate commit c369b05 in PR branch chore/315-wrapping-context with baseline commit 33504a3 in branch vlad/ci-auto-regen-requirements.

Found 0 performance improvements and 5 performance regressions! Performance is the same for 616 metrics, 10 unstable metrics.

scenario:iastaspects-lstrip_aspect

• 🟥 execution_time [+61.631µs; +70.961µs] or [+18.610%; +21.427%]

scenario:iastaspects-swapcase_noaspect

• 🟥 execution_time [+19.190µs; +23.554µs] or [+7.134%; +8.757%]

scenario:iastaspectsospath-ospathbasename_aspect

• 🟥 execution_time [+104.204µs; +111.891µs] or [+24.130%; +25.910%]

scenario:span-start

• 🟥 execution_time [+1.249ms; +1.431ms] or [+8.086%; +9.264%]

scenario:telemetryaddmetric-1-count-metric-1-times

• 🟥 execution_time [+230.431ns; +264.541ns] or [+11.117%; +12.762%]

[vlad-scherbich]

@P403n1x87 I've taken a look at the PR, and it makes sense to me for the most part. For the parts that I don't have much experience with, I've asked Claude for thoughts. Here are its findings, hopefully they will be helpful:

Must be fixed before merging

1. Hot-path callbacks iterate a mutable dict without synchronization (monitoring.py)

The callbacks (_on_py_start, _on_py_return, etc.) do:

entries = _registry.get(code)
# ...
for e in entries.values():
...

Meanwhile register() and unregister() mutate that same inner dict (entries[id(handler)] = entry / existing.pop(...)) while holding _registry_lock -- but the callbacks don't acquire the lock. If a register call adds or removes an entry between two iterations of the for loop (GIL can switch between next calls on the dict view), you get RuntimeError: dictionary changed size during iteration.

Fix options: (a) snapshot with list(entries.values()) in callbacks (one small allocation per event), (b) swap to a copy-on-write scheme where register/unregister replace the entire inner dict atomically (the reference assignment is GIL-atomic, so the callback always sees a consistent snapshot), or (c) hold the lock in callbacks (worst for latency).

Option (b) is the best tradeoff: zero allocation on the hot path, and register/unregister are cold.

Nice to have

2. Tool ID allocation starts at 0, competing with debuggers (monitoring.py)

for tid in range(6):
    try:
        sys.monitoring.use_tool_id(tid, "ddtrace")
...

IDs 0-2 are conventionally reserved (debugger, coverage, profiler). Starting from 0 means ddtrace could claim the debugger slot if no debugger is attached yet, then a later debugpy or pdb attach would fail to register. Starting from 3 (or iterating range(5, -1, -1) to prefer higher IDs) would be more neighborly.

3. _ENTER_FRAME_DEPTH = 3 is fragile (context.py)

_ENTER_FRAME_DEPTH = 3 if sys.version_info >= (3, 15) else 1

This assumes a fixed call-stack depth from the monitored function through the monitoring dispatch to enter. If CPython changes the monitoring callback invocation depth, or if the multiplexer adds/removes a level, this silently produces the wrong frame. Consider walking the stack looking for the code object that matches self.wrapped.code rather than assuming a depth.

[P403n1x87]

Awesome, thanks!

register() and unregister() mutate that same inner dict (entries[id(handler)] = entry / existing.pop(...)) while holding _registry_lock

The reasoning here was that it would be unlikely to have mutation while callbacks are invoked, because these are generally installed on enablement (boot). However RC might violate this assumption, so it won't cost us much to be a bit defensive here.

IDs 0-2 are conventionally reserved (debugger, coverage, profiler). Starting from 0 means ddtrace could claim the debugger slot if no debugger is attached yet, then a later debugpy or pdb attach would fail to register. Starting from 3 (or iterating range(5, -1, -1) to prefer higher IDs) would be more neighborly.

We are a debugger as a matter of fact 🙁 but I guess it doesn't matter where we start with the ID so we can just comply.

3. _ENTER_FRAME_DEPTH = 3 is fragile (context.py)

Deliberate choice. This value should be fixed for each Python release, so the cost is at most 1 update every year. Still much better than updating a whole bunch of opcodes 🙂