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