fix(telemetry): prevent spurious OTel context detach errors when async generators are cancelled

[mmphego]

Summary

Fixes #4894

Eliminates the noisy ERROR [opentelemetry.context] Failed to detach context log that appears whenever an in-flight agent run is interrupted mid-generation (e.g. a guardrail that blocks a request after the LLM has already started streaming).

Root Cause

tracer.start_as_current_span() returns a context manager that stores a contextvars.Token on enter and calls ContextVar.reset(token) on exit. A Token can only be reset in the same contextvars.Context object that produced it.

When an async generator using start_as_current_span() is closed from a different asyncio.Task — which happens when asyncio's asyncgen finalizer hook schedules aclose() via call_soon in the event-loop's base context — reset(token) raises ValueError.

otel_context.detach() catches this ValueError internally and logs it at ERROR level before returning, so the error is invisible to callers but still appears in logs.

Affected code paths

File	Location	Span
tracing.py	_use_native_generate_content_span_stable_semconv	generate_content {model}
tracing.py	_use_native_generate_content_span (experimental semconv)	generate_content {model}
base_agent.py	run_async	invoke_agent {name}
base_agent.py	run_live	invoke_agent {name}

Fix

Replace with tracer.start_as_current_span(...) in async generator bodies with manual span management:

span = tracer.start_span(name)
token = otel_context.attach(trace.set_span_in_context(span))
try:
    yield span
finally:
    _safe_detach(token)
    if span.is_recording():
        span.end()

_safe_detach() calls _RUNTIME_CONTEXT.detach() directly (bypassing OTel's logging wrapper) and silently absorbs ValueError when cleanup runs in a different context.

Span data is fully preserved (attributes, timing, parent relationships). Only the contextvars state restoration is skipped for generators that are being discarded — an acceptable trade-off.

Reproducer

import asyncio
from opentelemetry import context as otel_context, trace
from opentelemetry.context import _RUNTIME_CONTEXT
from opentelemetry.sdk.trace import TracerProvider

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer("test")

async def gen_with_span():
    with tracer.start_as_current_span("test_span"):
        yield "event"

async def main():
    gen = gen_with_span()
    await gen.__anext__()
    # Closing from a different Task reproduces the error:
    await asyncio.create_task(gen.aclose())  # logs ERROR: Failed to detach context

asyncio.run(main())

Testing

Reproducer and fix verification tests added in the linked issue. Key test cases:

• test_should_reproduce_error_when_generator_closed_from_different_task — confirms the bug exists with the raw start_as_current_span pattern
• test_should_not_error_with_adk_safe_span_pattern — confirms the _safe_detach pattern eliminates the error even under cross-context close

Checklist

• Bug reproduced with a minimal test case
• Fix verified: no ERROR logs after patching
• Span data preserved (manual span management is functionally equivalent)
• Both run_async and run_live paths fixed
• Both stable and experimental semconv paths fixed

[rohityan]

Hi @mmphego , Thank you for your contribution! We appreciate you taking the time to submit this pull request. Can you please fix the formatting errors

[mmphego]

@rohityan please run the workflows

[mmphego]

Bump!!

[RKest]

Hi @mmphego

Thank you for your contribution.

We're aware of this issue, and unfortunately this is a core limitation of how ContextVars & Python Async Generators interplay with each other.

The solution is to wrap all async generators in contextlib.aclosing, but we sometimes miss a few or, sometimes user code which interacts with ADK doesn't warp their Async Generators.

I fear replacing the OTel error message with a custom logger.debug, would only hurt discoverability of the error especially because it can also result in wrong span hierarchies, hence I don't think this should be merged in