refactor(loongsuite-instrumentation-langchain): GenAI Util Migration & ReAct Step Support by Cirilla-zmh · Pull Request #139 · alibaba/loongsuite-python-agent

Cirilla-zmh · 2026-03-10T06:43:14Z

Description

Summary

Refactors loongsuite-instrumentation-langchain to use opentelemetry-util-genai and adds ReAct step instrumentation for AgentExecutor and LangGraph agents.

Key Changes

Architecture

Replaced legacy wrapt-based function wrapping with LangChain BaseTracer callback mechanism
Migrated to ExtendedTelemetryHandler from opentelemetry-util-genai for standardized GenAI semantic conventions
Added RLock for thread safety in tracer callbacks

ReAct Step Instrumentation

Monkey-patched AgentExecutor._iter_next_step and _aiter_next_step to instrument each ReAct iteration
Dual patch: supports both langchain.agents (0.x) and langchain_classic.agents (1.x) when available
Covers invoke, ainvoke, stream, astream, batch, abatch
ReAct Step spans: gen_ai.span.kind=STEP, gen_ai.operation.name=react, gen_ai.react.round, gen_ai.react.finish_reason
Span hierarchy: Agent → ReAct Step → LLM/Tool

LangGraph ReAct Agent Support

Detects LangGraph agents via Run.metadata["_loongsuite_react_agent"] (injected by langgraph instrumentation)
Patches langchain.agents.create_agent to mark ReAct graphs (langchain ≥ 1.x)
Disambiguates top-level graph (Agent span) from child nodes (chain spans) using inside_langgraph_react propagation
Agent name resolution: inherits outer graph node name (e.g. invoke_agent product_agent) instead of generic invoke_agent LangGraph
Tracks ReAct step boundaries via callback-based detection of the "agent" node within the graph

Other Improvements

TTFT (Time To First Token) tracking for streaming
Content capture gating via experimental mode
Base64 image filtering for chain content
Token usage extraction logic fixes
Debug logging for exception handlers

Breaking Changes

Instrumentation architecture changed; span attributes and structure may differ from the previous implementation

Testing & CI

New test suite (~107 tests) with oldest/latest dependency matrices
Added GitHub workflows for lint and test

Fixes #136 (issue)

Type of change

Please delete options that are not relevant.

New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

Add unit tests

Does This PR Require a Core Repo Change?

No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

Followed the style guidelines of this project
Changelogs have been updated
Unit tests have been added
Documentation has been updated

- Add ExtendedTelemetryHandler with entry span and ReAct span support - Add propagation of session id and user id - Add _extended_common for shared types and utilities - Update gen_ai_extended_attributes for new span types - Add loongsuite workflows for CI Change-Id: I461f3febc206aea281741a01d00f38931483a4dc Co-developed-by: Cursor <noreply@cursor.com> Made-with: Cursor

…ndler - Integrate ExtendedTelemetryHandler for improved telemetry - Refactor LoongsuiteTracer with context propagation and content capture - Add ReAct step patch for langchain_classic - Refactor semconv and utility functions - Reorganize tests (chain, LLM, tool, retriever spans) - Update tox config for langchain testing Change-Id: I7c09df91dadd9d8ea75afba6502f6513fad800ad Co-developed-by: Cursor <noreply@cursor.com> Made-with: Cursor

Change-Id: I426ce98bc9e1eb2ebca2dfee5fbe0211d801809f Co-developed-by: Cursor <noreply@cursor.com>

…marking Add instrumentation for langchain.agents.create_agent (the new home of create_react_agent after LangGraph v1.0 deprecation). The wrapper marks the returned graph with _loongsuite_react_agent=True so that the langgraph Pregel stream/astream wrapper can inject metadata. Change-Id: Ie6a869ab107e0c91a55e6d2d79212f45d9234646 Co-developed-by: Cursor <noreply@cursor.com> Made-with: Cursor

Change-Id: Idff7ed598bdeb7c9846ffcee171abcce3af32994 Co-developed-by: Cursor <noreply@cursor.com>

Change-Id: I78074851d283e36996c94a31bd51a00322f4325e Co-developed-by: Cursor <noreply@cursor.com>

Change-Id: Ie6441ccd1be48d60b3a8740774ad1a290afe8d3f Co-developed-by: Cursor <noreply@cursor.com>

Change-Id: If6b8e985eb88df17e835ef66743003a08f401c91 Co-developed-by: Cursor <noreply@cursor.com>

Copilot

Pull request overview

This PR refactors loongsuite-instrumentation-langchain to use opentelemetry-util-genai via ExtendedTelemetryHandler and adds ReAct step instrumentation for AgentExecutor and LangGraph agents. The legacy wrapt-based function wrapping is replaced with a BaseTracer callback mechanism, and old tests are removed in favor of a new test suite.

Changes:

Replaced legacy tracer with ExtendedTelemetryHandler-based LoongsuiteTracer, adding support for LLM, Chain, Agent, Tool, Retriever, and ReAct Step spans with GenAI semantic conventions
Added monkey-patching of AgentExecutor._iter_next_step/_aiter_next_step for ReAct step instrumentation, plus LangGraph agent detection via metadata propagation
Rewrote test suite (~107 tests) with shared conftest.py fixtures, oldest/latest dependency matrices, and updated CI workflows

Reviewed changes

Copilot reviewed 31 out of 32 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
`tox-loongsuite.ini`	Enable langchain tests with oldest/latest matrix
`tests/conftest.py`	Shared pytest fixtures for instrumentation and export
`tests/test_basic.py`	Basic tracer injection and chain span tests
`tests/test_llm_spans.py`	LLM span creation and attribute tests
`tests/test_chain_spans.py`	Chain span creation and content tests
`tests/test_tool_spans.py`	Tool span creation and content tests
`tests/test_retriever_spans.py`	Retriever span creation and content tests
`tests/test_agent_spans.py`	Agent detection unit tests
`tests/test_react_step_patch.py`	ReAct step patch application and span tests
`tests/test_data_extraction.py`	Unit tests for data extraction helpers
`tests/test_instrumentor.py`	Instrumentor lifecycle tests
`tests/test_langchain_instrumentor.py`	Integration tests with RetrievalQA and ChatOpenAI
`tests/requirements.oldest.txt`	Oldest dependency pins for test matrix
`tests/requirements.latest.txt`	Latest dependency pins for test matrix
`internal/semconv.py`	Simplified to re-export from `util-genai`
`internal/_utils.py`	Refactored data extraction helpers
`internal/_tracer.py`	New `LoongsuiteTracer` based on `BaseTracer` and `ExtendedTelemetryHandler`
`internal/patch.py`	ReAct step monkey-patch for AgentExecutor
`__init__.py`	Instrumentor with agent executor and create_agent patching
`pyproject.toml`	Updated dependencies and metadata
`README.md`	Updated usage docs and traced operations table
`CHANGELOG.md`	Documented breaking changes and new features
`.github/workflows/loongsuite_test_0.yml`	CI test jobs for langchain oldest/latest
`.github/workflows/loongsuite_lint_0.yml`	CI lint job for langchain
Deleted old test files	Removed legacy test files under `tests/instrumentation/langchain/`

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/requirements.oldest.txt

...loongsuite-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/__init__.py

...te-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/internal/_tracer.py

instrumentation-loongsuite/loongsuite-instrumentation-langchain/CHANGELOG.md

instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/test_retriever_spans.py

...te-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/internal/_tracer.py

...loongsuite-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/__init__.py

...te-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/internal/_tracer.py

Change-Id: Iba0556ead60df26931a092d4c4d75d8dae2d949a Co-developed-by: Cursor <noreply@cursor.com>

123liuziming · 2026-03-10T11:01:37Z

...te-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/internal/_tracer.py

+    # _start_trace / _end_trace
+    # ------------------------------------------------------------------

    def _start_trace(self, run: Run) -> None:


不要调父类的_start_trace，如果没有需要的话在这里直接pass，调父类的_start_trace在之前导致过缓慢的内存泄漏。

123liuziming · 2026-03-10T11:01:46Z

...te-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/internal/_tracer.py

-            self._runs[run.id] = _Run(span=span, context=context)

    def _end_trace(self, run: Run) -> None:
        super()._end_trace(run)


123liuziming · 2026-03-10T11:14:10Z

...ite-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/internal/_utils.py

+

 def recursive_size(obj: Any, max_size: int = 10240) -> int:
    """递归计算对象大小，超过阈值时快速返回"""


这块代码可以删掉了，处理逻辑太复杂了，半年前线上的代码已经注释掉了base64这块的逻辑

123liuziming · 2026-03-10T11:16:22Z

...te-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/internal/_tracer.py

没找到reranker相关的逻辑

Cirilla-zmh added 5 commits March 10, 2026 14:20

Fix logic of token usage extraction

b517483

Change-Id: I426ce98bc9e1eb2ebca2dfee5fbe0211d801809f Co-developed-by: Cursor <noreply@cursor.com>

Add necessary debug logs

62ede15

Change-Id: Idff7ed598bdeb7c9846ffcee171abcce3af32994 Co-developed-by: Cursor <noreply@cursor.com>

github-actions bot assigned 123liuziming, Cirilla-zmh and ralf0131 Mar 10, 2026

github-actions bot requested review from 123liuziming and ralf0131 March 10, 2026 06:43

Cirilla-zmh added documentation Improvements or additions to documentation enhancement New feature or request instrumentaion The instrumentation label represents issues related to instrumentation. genai The genai label represents issues related to generative AI. labels Mar 10, 2026

Cirilla-zmh added 3 commits March 10, 2026 14:44

Fix related PR

a0943dd

Change-Id: I78074851d283e36996c94a31bd51a00322f4325e Co-developed-by: Cursor <noreply@cursor.com>

Add legacy unit test

257cbc0

Change-Id: Ie6441ccd1be48d60b3a8740774ad1a290afe8d3f Co-developed-by: Cursor <noreply@cursor.com>

format

a30ab5b

Change-Id: If6b8e985eb88df17e835ef66743003a08f401c91 Co-developed-by: Cursor <noreply@cursor.com>

ralf0131 requested a review from Copilot March 10, 2026 08:50

Copilot AI reviewed Mar 10, 2026

View reviewed changes

Copilot started reviewing on behalf of ralf0131 March 10, 2026 09:12 View session

feedback

ede082d

Change-Id: Iba0556ead60df26931a092d4c4d75d8dae2d949a Co-developed-by: Cursor <noreply@cursor.com>

123liuziming reviewed Mar 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(loongsuite-instrumentation-langchain): GenAI Util Migration & ReAct Step Support#139

refactor(loongsuite-instrumentation-langchain): GenAI Util Migration & ReAct Step Support#139
Cirilla-zmh wants to merge 9 commits intoalibaba:mainfrom
Cirilla-zmh:feat/langchain-instrumentation-refactor

Cirilla-zmh commented Mar 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

123liuziming Mar 10, 2026

Uh oh!

123liuziming Mar 10, 2026

Uh oh!

123liuziming Mar 10, 2026

Uh oh!

123liuziming Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants



		def recursive_size(obj: Any, max_size: int = 10240) -> int:
		"""递归计算对象大小，超过阈值时快速返回"""

Conversation

Cirilla-zmh commented Mar 10, 2026

Description

Summary

Key Changes

Architecture

ReAct Step Instrumentation

LangGraph ReAct Agent Support

Other Improvements

Breaking Changes

Testing & CI

Type of change

How Has This Been Tested?

Does This PR Require a Core Repo Change?

Checklist:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

123liuziming Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

123liuziming Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

123liuziming Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

123liuziming Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants