fix(langchain): activate context at execution boundaries instead of in callbacks by sangkyoonnam · Pull Request #818 · open-telemetry/opentelemetry-python-genai

sangkyoonnam · 2026-09-30T14:33:01Z

Description

On top of #817 and the LangChain part of @lmolkova's prototype for #677, kept as the first commit with her authorship. Context activation moves from callbacks to the LangChain and LangGraph execution boundaries (chat models, tools, retrievers, runnables, composites, branches, single-input batches, streams, graph nodes), so attach and detach happen in the same Python context and nested SDK and HTTP spans correlate across asyncio tasks and threads. The commits after hers cover what the prototype missed: plain Runnable subclasses and composites, lazy stream config, missing-boundary handling, and main's chat span leak when ainvoke is cancelled or interrupted, fixed here because it sits on this boundary.

Known gaps: requires langchain >= 0.3.22 (core 0.3.46 added set_config_context) and the workspace util-genai 1.3b0.dev; graph-node propagation needs LangGraph >= 0.3.18. A plain invoke override under multi-input batch/abatch stays unparented, as on main; strict xfails. Private boundaries that are missing are skipped, with a warning for installed libraries. batch_as_completed has no dedicated test. A trivial RunnableLambda.invoke costs 18 to 19 us more than main on Python 3.12. The app probes ran on latest dependencies before the interrupt cleanup; examples/manual and zero-code are unrun.

Refs #677.

Type of change

Bug fix (non-breaking change which fixes an issue)

How has this been tested?

New tests in test_custom_execution_context.py, test_execution_context.py, test_stream_context.py, test_persistence_context.py cover span parenting, HTTP traceparent through instrumented httpx, cross-task stream reads, cancellation, interruption, lazy config and instrumentation restoration. Each fix has a test that fails on the commit before it.
tox -e py312-test-instrumentation-genai-langchain-latest: 620 passed, 2 xfailed; -oldest (langchain 0.3.22, langgraph 0.3.18): 565 passed, 21 skipped, 2 xfailed; util 520; openai 394; typecheck; precommit; langchain conformance 12 passed.
A local create_agent app with streaming ChatOpenAI, tools and a mock server, on main, fix(util-genai,openai): scope stream invocation context #817 and this branch: astream consumed in another task, batch, a thread pool, mid-stream cancel, a two-turn checkpointer and the util-genai: GenAIInvocation._finish detaches its context token unguarded; async LangChain runs log a traceback per invocation #677 shape. On main the async cases leave the provider chat span and its HTTP child as orphan roots; here every span has its parent and the caller's context is restored. All three states log zero detach errors.

Checklist

Followed the style guidelines of this project
Changelog updated if the change requires an entry
Unit tests added
Documentation updated

…enAI part) Keep callback-managed spans detached and activate their context around framework execution boundaries, including custom tools and retrievers, streaming, and graph persistence. Add inference and HTTP correlation tests covering concurrency, cancellation, and context restoration. Assisted-by: GPT-6

…agments

…art) Keep callback-managed spans detached and activate their context around framework execution boundaries, including custom tools and retrievers, streaming, and graph persistence. Add inference and HTTP correlation tests covering concurrency, cancellation, and context restoration. Assisted-by: GPT-6

…ndary

…e floor

…input batches

…re warning

… current

… stream finalizer

…am entry points

…upted mid-stream

opentelemetry-pr-dashboard · 2026-09-30T14:37:32Z

Pull request dashboard status

Waiting on the author · refreshed 2026-10-06 22:24 UTC

Respond to 1 review item (e.g. link a commit, explain why not, ask a follow-up):

Top-level threads: 1

Status above doesn't look right?

Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
Should this be with reviewers? Comment /dashboard route:reviewers to route it to them.
Anything wrong — including the routing? Report it with what you expected; it helps us improve the dashboard.

Copilot

Copilot review overview

🟡 Changes recommended

LangChain telemetry finalization can still replace an underlying BaseException because its guard catches only Exception.

Review effort: Balanced
Findings: 1

Open (1)

Catch BaseException during telemetry finalization · New

What changed in this PR

Moves LangChain/LangGraph span-context activation from callbacks to execution boundaries, while extending stream wrappers to scope context per read and cleanup.

Changes:

Adds execution-boundary instrumentation for LangChain/LangGraph calls, streams, batches, and graph nodes.
Adds reusable stream execution-context hooks and applies them to OpenAI streams.
Expands context propagation, cancellation, failure, and restoration tests.

File	Description
`uv.lock`	Updates LangChain dependency floor.
`util/opentelemetry-util-genai/tests/test_stream.py`	Tests scoped stream operations.
`util/opentelemetry-util-genai/src/opentelemetry/util/genai/stream.py`	Adds execution-context stream hooks.
`util/opentelemetry-util-genai/README.rst`	Documents the new stream hook.
`util/opentelemetry-util-genai/AGENTS.md`	Updates stream guidance.
`util/opentelemetry-util-genai/.changelog/817.added`	Records the new hook.
`README.md`	Updates the LangChain version floor.
`instrumentation/opentelemetry-instrumentation-genai-openai/tests/test_responses_stream_context.py`	Tests Responses stream context.
`instrumentation/opentelemetry-instrumentation-genai-openai/tests/test_response_wrappers.py`	Updates wrapper test fixtures.
`instrumentation/opentelemetry-instrumentation-genai-openai/tests/test_chat_stream_context.py`	Tests chat stream context.
`instrumentation/opentelemetry-instrumentation-genai-openai/tests/requirements.oldest.txt`	Uses the workspace stream utility.
`instrumentation/opentelemetry-instrumentation-genai-openai/src/opentelemetry/instrumentation/genai/openai/response_wrappers.py`	Scopes Responses stream execution.
`instrumentation/opentelemetry-instrumentation-genai-openai/src/opentelemetry/instrumentation/genai/openai/chat_wrappers.py`	Scopes chat stream execution.
`instrumentation/opentelemetry-instrumentation-genai-openai/pyproject.toml`	Raises the util dependency floor.
`instrumentation/opentelemetry-instrumentation-genai-openai/.changelog/817.fixed`	Records OpenAI context fixes.
`instrumentation/opentelemetry-instrumentation-genai-langchain/tests/test_stream_context.py`	Tests lazy and cross-task streams.
`instrumentation/opentelemetry-instrumentation-genai-langchain/tests/test_persistence_context.py`	Tests checkpoint/store context.
`instrumentation/opentelemetry-instrumentation-genai-langchain/tests/test_execution_context.py`	Tests execution-boundary propagation.
`instrumentation/opentelemetry-instrumentation-genai-langchain/tests/test_custom_execution_context.py`	Tests custom runnable boundaries.
`instrumentation/opentelemetry-instrumentation-genai-langchain/tests/test_callback_handler.py`	Updates non-attaching callback expectations.
`instrumentation/opentelemetry-instrumentation-genai-langchain/tests/test_agent_classification_corpus.py`	Updates agent invocation expectations.
`instrumentation/opentelemetry-instrumentation-genai-langchain/tests/requirements.oldest.txt`	Adds oldest boundary-capable dependencies.
`instrumentation/opentelemetry-instrumentation-genai-langchain/tests/requirements.latest.txt`	Adds integration-test dependencies.
`instrumentation/opentelemetry-instrumentation-genai-langchain/src/opentelemetry/instrumentation/genai/langchain/package.py`	Raises the LangChain floor.
`instrumentation/opentelemetry-instrumentation-genai-langchain/src/opentelemetry/instrumentation/genai/langchain/callback_handler.py`	Stops callbacks from attaching context.
`instrumentation/opentelemetry-instrumentation-genai-langchain/src/opentelemetry/instrumentation/genai/langchain/_run_context.py`	Manages per-run execution scopes.
`instrumentation/opentelemetry-instrumentation-genai-langchain/src/opentelemetry/instrumentation/genai/langchain/_execution_context.py`	Patches LangChain execution boundaries.
`instrumentation/opentelemetry-instrumentation-genai-langchain/src/opentelemetry/instrumentation/genai/langchain/__init__.py`	Wires boundary instrumentation lifecycle.
`instrumentation/opentelemetry-instrumentation-genai-langchain/README.rst`	Documents support and limitations.
`instrumentation/opentelemetry-instrumentation-genai-langchain/pyproject.toml`	Raises dependency floors.
`instrumentation/opentelemetry-instrumentation-genai-langchain/.changelog/818.fixed`	Records context propagation fixes.
`instrumentation/opentelemetry-instrumentation-genai-langchain/.changelog/818.changed`	Records dependency requirements.
`AGENTS.md`	Updates repository stream guidance.
`.github/instructions/instrumentation.instructions.md`	Updates instrumentation review guidance.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+        except Exception:
+            _logger.exception("Failed to finalize LangChain run")


…ntext

… inside the stream execution context

…r exit

lmolkova · 2026-10-06T00:01:24Z

4 async composite tests fail on oldest (Python 3.10): test_plain_runnable_in_composite_correlates_http[async-*] and test_plain_runnable_fallback_correlates_http[async]. langchain-core < 1.5 on Python < 3.11 doesn't run async steps in the copied context. How about skipping them on that combination?

requires_async_step_context = pytest.mark.skipif(
    sys.version_info < (3, 11)
    and Version(version("langchain-core")) < Version("1.5.0"),
    reason="langchain-core < 1.5 on Python < 3.11 doesn't run async steps in the copied context",
)

lmolkova · 2026-10-05T23:21:28Z

+    # (a chat model invoked from a lambda body): attaching that one here would
+    # leave its ended span current for the rest of this frame.
+    config = dict(bound.arguments.get("config") or {})
+    scope.run_id = config.get("run_id") or uuid4()


LangChain mints run ids with uuid7 (time-ordered; LangSmith says future versions will require v7), so injecting uuid4 here and in _wrap_run changes the ids every tracer sees for runnables, tools, retrievers and streams. Could we reuse LangChain's generator when it's available?

try: from langchain_core.utils.uuid import uuid7 as _new_run_id except ImportError: # older langchain-core from uuid import uuid4 as _new_run_id

Suggested change

scope.run_id = config.get("run_id") or uuid4()

scope.run_id = config.get("run_id") or _new_run_id()

Done in 8b3015b. _new_run_id is langchain_core.utils.uuid.uuid7 when the import works and uuid4 otherwise, and both _config_run and _wrap_run go through it. On langchain-core 1.6.6 the ids come out version 7; on the oldest pin (0.3.49) the module doesn't exist, so it falls back to uuid4, which is what those cores mint themselves.

lmolkova · 2026-10-05T23:21:28Z

+            if isinstance(config, Sequence):
+                config = cast(Any, config[0])


Suggested change

if isinstance(config, Sequence):

config = cast(Any, config[0])

if isinstance(config, Sequence):

config = cast(Any, config[0]) if config else None

Done in 8b3015b. With config=[] and one input the old line raised IndexError from the wrapper before LangChain's own ValueError about the config count; now the wrapper returns no parent and LangChain's error surfaces.

…hain-core < 1.5

sangkyoonnam · 2026-10-06T14:04:23Z

Done in db80ddf, with your marker as written. Only the async params carry it (pytest.param("async", marks=requires_async_step_context)), so the sync cases still run there. py310 oldest (langchain-core 0.3.49): those 4 are now skipped (561 passed, 25 skipped in all, 21 of them pre-existing); without the marker the same 4 fail. py312 oldest: nothing new skipped, 565 passed. py312 latest (1.6.6): 620 passed.

lmolkova

thanks for working on it!

Let's get #817 in first and then rebase this one on it, so this PR only carries the LangChain changes.

lmolkova and others added 21 commits September 30, 2026 22:04

fix(openai): suspend Responses API stream invocations between reads

e7e7a3c

docs: describe the stream execution context hook and add changelog fr…

29a4afd

…agments

docs: name the changelog fragments after the pull request

b493216

fix(langchain): activate context around Runnable._call_with_config

661226f

fix(langchain): skip missing execution boundaries when instrumenting

c8992e6

test(langchain): cover Responses API stream consumers

68b988e

fix(langchain): attach the parent context where composites enter a step

4665d51

fix(langchain): read the stream config on the first advancement

f34d609

fix(langchain): warn when an installed library lacks an execution bou…

cb5c1a4

…ndary

docs(langchain): list where context is propagated and the remaining gaps

574c447

fix(langchain): find the LangGraph node boundary in pre-0.6 releases

be1f8c5

chore(langchain): require langchain 0.3.22 and test its langchain-cor…

f5e5b7a

…e floor

fix(langchain): attach the parent context for branch runs and single-…

ecb53ca

…input batches

fix(langchain): detect the installed library by its distribution befo…

299e215

…re warning

chore(langchain): test LangGraph 0.3.18 as the oldest supported release

bb030a5

fix(langchain): skip the run scope attach when its context is already…

54d6b18

… current

docs(langchain): explain the patch targets, the run id choice and the…

f055087

… stream finalizer

test(langchain): pin the wrap order and restoration of the graph stre…

e1d9690

…am entry points

fix(langchain): end the chat span when ainvoke is cancelled or interr…

1aa6a66

…upted mid-stream

Copilot AI balanced review requested due to automatic review settings September 30, 2026 14:33

sangkyoonnam requested a review from a team as a code owner September 30, 2026 14:33

github-project-automation Bot added this to GenAI Semantic Conventions and Instrumentation libraries Sep 30, 2026

docs(langchain): name the changelog fragments after the pull request

02612b0

Copilot started reviewing on behalf of sangkyoonnam September 30, 2026 14:33 View session

sangkyoonnam mentioned this pull request Sep 30, 2026

util-genai: leave a foreign context untouched when an invocation finishes in another task #785

Closed

4 of 5 tasks

opentelemetry-pr-dashboard Bot mentioned this pull request Sep 30, 2026

Pull Request Dashboard #171

Open

Copilot AI reviewed Sep 30, 2026

View reviewed changes

Comment thread ...umentation-genai-langchain/src/opentelemetry/instrumentation/genai/langchain/_run_context.py

Comment on lines +90 to +91

except Exception:

_logger.exception("Failed to finalize LangChain run")

sangkyoonnam added 3 commits September 30, 2026 23:49

fix(util): run the stream manager exit inside the stream execution co…

35867a4

…ntext

fix(openai): finalize a close through the Responses API HTTP response…

b2538dc

… inside the stream execution context

docs(util): note the execution context on close finalizers and manage…

4253242

…r exit

lmolkova reviewed Oct 6, 2026

View reviewed changes

sangkyoonnam added 3 commits October 6, 2026 10:14

Merge branch 'main' into fix/677-langchain-execution-context-split

4ef42d0

fix(langchain): mint run ids with LangChain's uuid7 when available

8b3015b

test(langchain): skip async composite cases on Python 3.10 with langc…

db80ddf

…hain-core < 1.5

lmolkova reviewed Oct 6, 2026

View reviewed changes

Navigation Menu

Repository navigation

fix(langchain): activate context at execution boundaries instead of in callbacks - #818

fix(langchain): activate context at execution boundaries instead of in callbacks#818
sangkyoonnam wants to merge 28 commits into
open-telemetry:mainfrom
sangkyoonnam:fix/677-langchain-execution-context-split

sangkyoonnam commented Sep 30, 2026

Uh oh!

opentelemetry-pr-dashboard Bot commented Sep 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

lmolkova commented Oct 6, 2026

Uh oh!

lmolkova Oct 5, 2026

Uh oh!

sangkyoonnam Oct 6, 2026

Uh oh!

lmolkova Oct 5, 2026

Uh oh!

sangkyoonnam Oct 6, 2026

Uh oh!

sangkyoonnam commented Oct 6, 2026

Uh oh!

lmolkova left a comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		except Exception:
		_logger.exception("Failed to finalize LangChain run")

	scope.run_id = config.get("run_id") or uuid4()
	scope.run_id = config.get("run_id") or _new_run_id()

		if isinstance(config, Sequence):
		config = cast(Any, config[0])

Conversation

sangkyoonnam commented Sep 30, 2026

Description

Type of change

How has this been tested?

Checklist

Uh oh!

opentelemetry-pr-dashboard Bot commented Sep 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request dashboard status

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

lmolkova commented Oct 6, 2026

Uh oh!

lmolkova Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

sangkyoonnam Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

lmolkova Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

sangkyoonnam Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

sangkyoonnam commented Oct 6, 2026

Uh oh!

lmolkova left a comment

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

opentelemetry-pr-dashboard Bot commented Sep 30, 2026 •

edited

Loading