fix(tracing): record cancellation in observation context managers

[lumman0]

What does this PR do?

Record asyncio.CancelledError escaping start_as_current_observation as an observation error, matching the existing @observe behavior introduced in #1566.

asyncio.CancelledError inherits from BaseException, so the underlying OpenTelemetry context manager's ordinary exception handling does not mark the span as an error. Before this change, cancelling a task inside the native observation context manager ends the observation without cancellation diagnostics, while an equivalent @observe call records ERROR and CancelledError.

This can occur when a service cancels an in-flight operation during shutdown, or when asyncio.wait_for cancels an operation on timeout.

The shared context manager now:

• Records level="ERROR" and the cancellation message, falling back to CancelledError when the message is empty.
• Re-raises the original cancellation, preserving task cancellation and timeout behavior.
• Updates only a recording span, avoiding a second update when @observe has already recorded and ended it.
• Preserves end_on_exit=False, span parenting, and context cleanup.

The public method docstring documents the behavior. Eight regression cases cover span/generation observations, actual task cancellation with and without a message, timeout cancellation, context restoration, and manual ending. All eight failed against the unchanged base and pass with this fix.

Related work: #1566 fixed the decorator path. #1868 addresses helper-thread exception propagation, and #1893 addresses generator wrappers in observe.py; neither changes this native context-manager path. This PR follows the existing decorator's error classification for cancellation.

Type of change

• Bug fix
• New feature
• Breaking change
• Refactor
• Documentation update
• Tooling, CI, or repo maintenance

Verification

Tested on Windows with Python 3.12.14, SDK base f6b7040 (v4.17.0), and OpenTelemetry SDK 1.45.0.

uv run --frozen pytest tests/unit/test_otel.py tests/unit/test_observe.py tests/unit/test_resource_manager.py tests/unit/test_propagate_attributes.py -q -o log_cli=false --tb=short --timeout=30
# 233 passed, 2 skipped; one existing trace-IO deprecation warning

uv run --frozen ruff check .
uv run --frozen ruff format --check langfuse/_client/client.py tests/unit/test_otel.py
uv run --frozen python -m mypy langfuse --no-error-summary
git diff --check

Also verified with synthetic calls sent through real OTLP ingestion to a local self-hosted Langfuse v4.47.0 instance, then queried the persisted observations using the v2 observations API:

Case	Before	After
Native context manager, cancelled task	DEFAULT, no status message	ERROR, CancelledError
@observe, cancelled task	ERROR, CancelledError	ERROR, CancelledError
Native context manager, ValueError control	ERROR, ValueError: synthetic failure	ERROR, ValueError: synthetic failure

The full unit suite, full repository e2e suite, and live-provider suite were not run. Verification focused on the affected tracing/decorator/resource-manager/propagation paths plus the local persisted-data reproduction; no real model calls are needed for cancellation handling. Other Python versions remain for CI.

Checklist

• I self-reviewed the diff using code_review.md.
• I added or updated tests for behavior changes.
• I updated docs, examples, or .env.template if needed.
• I did not hand-edit generated files; if generated files changed, I used the upstream regeneration path.
• I did not commit secrets or credentials.

Confidence Score: 5/5

This PR appears safe to merge; no actionable issues were found.

What we checked:

• Decorator records cancellation twice: The decorator calls end() before leaving the context. The new handler checks is_recording() and skips the ended span.

Summary

Records asyncio.CancelledError escaping an observation context as ERROR, then re-raises it.

• Uses the cancellation message, with CancelledError as the fallback.
• Skips updates to ended or non-recording spans.
• Adds eight cases covering cancellation, timeouts, parent restoration, and end_on_exit=False.

No actionable issues were found. Tests were inspected but not run.

lumman0 explicitly described updating only recording spans as intentional.

_{Reviews (1) · Last reviewed commit: "fix(tracing): record cancellation in obs..."}

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[CLAassistant]

All committers have signed the CLA.

[chrikrah]

@lumman0 approving at 9d0ba8d. Your base/head split reproduces on Python 3.14.

$ python -m pytest tests/unit/test_otel.py -q -p no:cacheprovider    # opentelemetry-sdk 1.45.0
# head 9d0ba8d
73 passed, 2 skipped
# head tests, client.py from base f6b7040
8 failed, 65 passed, 2 skipped

non-blocking question: neither path emits an exception event on cancellation, and @observe emits none even for a RuntimeError; only the context manager records one, through use_span, for Exception subclasses. Probe at head, saved as tests/unit/exc_probe.py:

import asyncio, pytest
from langfuse import observe

@pytest.mark.parametrize("exc", [RuntimeError("boom"), asyncio.CancelledError("stop"), KeyboardInterrupt("ki")])
@pytest.mark.parametrize("path", ["cm", "observe"])
def test_probe(langfuse_memory_client, get_span, exc, path):
    def body():
        raise exc
    with pytest.raises(type(exc)):
        if path == "cm":
            with langfuse_memory_client.start_as_current_observation(name="obs"):
                body()
        else:
            observe(name="obs")(body)()
    langfuse_memory_client.flush()
    s = get_span("obs")
    print(f"\n{path:8} {type(exc).__name__:18} status={s.status.status_code.name} events={[e.name for e in s.events]}")

$ python -m pytest tests/unit/exc_probe.py -q -s -p no:cacheprovider    # head 9d0ba8d
cm       RuntimeError       status=ERROR events=['exception']
cm       CancelledError     status=ERROR events=[]
cm       KeyboardInterrupt  status=UNSET events=[]
observe  RuntimeError       status=ERROR events=[]
observe  CancelledError     status=ERROR events=[]
observe  KeyboardInterrupt  status=UNSET events=[]
6 passed, 4 warnings in 0.16s

If you want the event for cancellation, otel_span.record_exception(error) before the update adds it here, and the decorator would need the same. Matching @observe as it stands is also a fine answer.

@hassiebp could you review this one?

[lumman0]

@chrikrah Thanks for validating this! This PR keeps cancellation handling consistent with @observe, so it does not add an exception event. Whether cancellation should also emit an exception event can be discussed separately.