Bug report

Background

I have been writing a set of guided workshops on Tachyon as a way of learning it (https://github.com/GrahamDumpleton/tachyon-workshops), using an AI agent to generate the workshop content. While working on a workshop about exception mode, the agent found that a function which catches exceptions had far fewer samples in --mode exception when called from a generator expression than when called from a plain loop, with nothing else changed. It reduced that to the script below and believes there is a disparity between what the documentation says exception mode records and what it actually records.

That seems reasonable to me, but I do not have the knowledge of the internals to say whether this is a bug, a known shortcoming, or by design, so I am reporting what was found and how to reproduce it. The analysis of the cause at the end is the agent's, and I cannot evaluate it myself.

What the documentation says

The exception mode section of the profiling.sampling docs says samples are recorded when an exception is being propagated, "or when code is executing inside an except block where exception information is still present in the thread state". There is no mention of generators or coroutines being treated differently.

What happens

An except block that runs inside a generator or a coroutine, or in an ordinary function called from one, is never sampled in exception mode. The same except block in a plain function is sampled as expected.

The script below has five cases. Each raises ValueError, catches it, and spends one second in a busy loop inside the except block. They differ only in what kind of frame the handler, or its caller, is.

import asyncio
import time


def busy(seconds):
    end = time.perf_counter() + seconds
    while time.perf_counter() < end:
        pass


def handler_in_function():
    try:
        raise ValueError("handled in a function")
    except ValueError:
        busy(1.0)


def handler_in_generator():
    try:
        raise ValueError("handled in a generator")
    except ValueError:
        busy(1.0)
    yield


def handler_in_genexpr_callee():
    try:
        raise ValueError("handled in a function called from a generator expression")
    except ValueError:
        busy(1.0)


async def handler_in_coroutine():
    try:
        raise ValueError("handled in a coroutine")
    except ValueError:
        busy(1.0)


async def calls_handler_from_coroutine():
    handler_in_coroutine_callee()


def handler_in_coroutine_callee():
    try:
        raise ValueError("handled in a function called from a coroutine")
    except ValueError:
        busy(1.0)


handler_in_function()
for _ in handler_in_generator():
    pass
list(handler_in_genexpr_callee() for _ in range(1))
asyncio.run(handler_in_coroutine())
asyncio.run(calls_handler_from_coroutine())

Run it in wall-clock mode and then in exception mode:

python -m profiling.sampling run --mode wall --sort cumtime -l 40 --no-summary repro.py
python -m profiling.sampling run --mode exception --sort cumtime -l 40 --no-summary repro.py

Wall-clock mode sees all five handlers for about a second each (rows for repro.py only):

Captured 5080 samples in 5.08 seconds
       nsamples   sample%   tottime (s)    cumul%   cumtime (s)  filename:lineno(function)
      4969/4969      98.0         4.969      98.0         4.969  repro.py:7(busy)
         0/1000       0.0         0.000      19.7         1.000  repro.py:15(handler_in_function)
         0/1000       0.0         0.000      19.7         1.000  repro.py:51(<module>)
         0/1000       0.0         0.000      19.7         1.000  repro.py:22(handler_in_generator)
         0/1000       0.0         0.000      19.7         1.000  repro.py:52(<module>)
         0/1000       0.0         0.000      19.7         1.000  repro.py:30(handler_in_genexpr_callee)
         0/1000       0.0         0.000      19.7         1.000  repro.py:54(<genexpr>)
         0/1000       0.0         0.000      19.7         1.000  repro.py:54(<module>)
         0/1000       0.0         0.000      19.7         1.000  repro.py:37(handler_in_coroutine)
         0/1000       0.0         0.000      19.7         1.000  repro.py:55(<module>)
         0/1000       0.0         0.000      19.7         1.000  repro.py:48(handler_in_coroutine_callee)
         0/1000       0.0         0.000      19.7         1.000  repro.py:41(calls_handler_from_coroutine)
         0/1000       0.0         0.000      19.7         1.000  repro.py:56(<module>)
           0/66       0.0         0.000       1.3         0.066  repro.py:1(<module>)
          31/31       0.6         0.031       0.6         0.031  repro.py:8(busy)

Exception mode sees only the first:

Captured 5075 samples in 5.08 seconds
       nsamples   sample%  tottime (ms)    cumul%   cumtime (s)  filename:lineno(function)
         0/1000       0.0         0.000     100.0         1.000  repro.py:15(handler_in_function)
         0/1000       0.0         0.000     100.0         1.000  repro.py:51(<module>)
        993/993      99.3       993.000      99.3         0.993  repro.py:7(busy)
            7/7       0.7         7.000       0.7         0.007  repro.py:8(busy)

The exception mode run reports an error rate of 0.00 and captured over 5000 samples, so the samples were taken; they were then discarded by the mode's filter. From inside the program, sys.exception() returns the ValueError in every one of the five handlers.

This was reproduced on two builds of 3.15.0rc2, the python:3.15-rc-slim Docker image (GCC) and the python-build-standalone build installed by uv (Clang), both on Linux aarch64 in a container, as a non-root user, using run so no ptrace permission is involved.

If the behaviour is intended, the practical effect seems worth noting in the docs: in an asyncio program every except block runs in a coroutine or in something called from one, so exception mode reports almost nothing for the whole program, which reads as "exceptions are not your problem" rather than as a limitation.

AI analysis of the cause (not verified by me)

What follows is the agent's reading of the source. I am including it in case it saves someone time, but I cannot judge whether it is right.

In Modules/_remote_debugging/threads.c, the check that sets THREAD_STATUS_HAS_EXCEPTION reads current_exception and then exc_state.exc_value, the exception stack entry embedded in PyThreadState, with a comment that "nested exception handlers where exc_info points elsewhere are rare":

    // Check exc_state.exc_value (exception being handled in except block)
    // exc_state is embedded in PyThreadState, so we read it directly from
    // the thread state buffer. This catches most cases; nested exception
    // handlers where exc_info points elsewhere are rare.
    if (!has_exception) {
        uintptr_t exc_value = GET_MEMBER(uintptr_t, ts,
            unwinder->debug_offsets.thread_state.exc_state +
            unwinder->debug_offsets.err_stackitem.exc_value);
        if (exc_value != 0) {
            has_exception = 1;
        }
    }

The agent's explanation is that the interpreter records a handled exception in tstate->exc_info->exc_value, and that while a generator or coroutine is running, exc_info points at the generator's own _PyErr_StackItem rather than the thread's exc_state. A handler running in the generator, or in anything it calls, writes to the generator's entry, so exc_state stays empty and the profiler sees no exception. That would make the "rare" case every except block in every async def. It also matches the case of a plain function called from a generator expression being missed even though the handler is not itself in a generator.

It also noted that PR #142561, which added the mode, describes the check as using exc_info, and that a review comment on the docs (#142561 (comment)) pointed out the code reads exc_state; the field name was then removed from the docs. The tests in test_external_inspection.py (TestExceptionDetectionScenarios) describe the condition as "exc_info->exc_value is set" but only put the handler in a plain function, where the two coincide.

The suggested fix was to add exc_info to the debug offsets, use the embedded exc_state value when exc_info points at it (as now, at no extra cost), and otherwise read the _PyErr_StackItem it points at and walk previous_item, as _PyErr_GetTopmostException does. Whether that is the right approach, or whether changing the debug offsets is acceptable at this stage, is beyond what I can assess.

CPython versions tested on:

3.15

Operating systems tested on:

Linux

Linked PRs

• gh-158539: Fix exception mode missing handlers in generators/coroutines #158581
• [3.15] gh-158539: Fix exception mode missing handlers in generators/coroutines (GH-158581) #158852
• [3.14] gh-158539: Fix macOS runtime section lookup for remote debugging (GH-158874) #158906