Refactor loongsuite instrumentation for langchain

[Cirilla-zmh]

Description

Summary

Rewrites loongsuite-instrumentation-langchain from scratch, replacing the legacy wrapt-based function wrapping with a BaseTracer callback approach and integrating opentelemetry-util-genai for standardized GenAI semantic convention compliance.

Design

Tracer architecture — LoongsuiteTracer extends langchain_core.tracers.base.BaseTracer and hooks into the fine-grained _on_*_start / _on_*_end / _on_*_error callbacks. This lets us extract telemetry at the point where LangChain's Run objects are fully populated, rather than monkey-patching individual methods.

Operation type mapping — Each LangChain run type is mapped to the appropriate util-genai handler method:

• LLM / chat_model → start_llm / stop_llm / fail_llm
• Chain (Agent) → start_invoke_agent / stop_invoke_agent / fail_invoke_agent
• Chain (generic) → direct span creation with CHAIN span kind
• Tool → start_execute_tool / stop_execute_tool / fail_execute_tool
• Retriever → start_retrieve / stop_retrieve / fail_retrieve
  Agent runs are distinguished from generic chains by run.name (e.g. AgentExecutor, MRKLChain).

Context propagation — Follows the Robin/OpenLLMetry pattern: parent-child span relationships are established by passing Context explicitly to start_span / handler.start_*, avoiding hazardous attach/detach in a callback system where exceptions between callbacks can leak context. The sole exception is generic Chain spans, which do attach/detach so that non-LangChain child operations (e.g. HTTP calls) nest correctly.

Content capture gating — Chain input.value / output.value attributes are gated behind util-genai's is_experimental_mode() and get_content_capturing_mode(), consistent with how LLM/Tool/Retriever content is already controlled.

Thread safety — All access to the per-run bookkeeping dict is protected by RLock.

TTFT — on_llm_new_token records the monotonic first-token timestamp; util-genai computes gen_ai.response.time_to_first_token on span finalization.

Changes to util-genai

• All start_* methods in handler.py and extended_handler.py accept an optional context parameter, forwarded to start_span for explicit parent-child linking.
• _safe_detach uses _RUNTIME_CONTEXT.detach directly to avoid the noisy ERROR log from the OTel SDK's context_api.detach wrapper.
• Fixed undefined otel_context reference in _multimodal_processing.py.

##Test plan

• 98 tests covering: instrumentor lifecycle, LLM/Chain/Agent/Tool/Retriever span creation, input/output content capture with enable/disable, error spans, data extraction utilities, and multi-step chain composition.
• tox-loongsuite.ini configured with oldest / latest dependency matrices.
• Zero ERROR-level log output during test execution.

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)

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

[Cirilla-zmh]

PR #133 代码审查结果

✅ 符合规范的项目

1. pyproject.toml 配置正确 - 与其他同类 instrumentation 一致
2. 包含 version 文件 - 内容为 0.2.0.dev，符合开发版本规范
3. 包含 package 文件 - 正确设置了 langchain_core 依赖版本
4. LICENSE 文件头完整 - 所有文件都包含正确的 Apache 2.0 LICENSE 头
5. CHANGELOG 已更新 - 包含了 0.1.0 版本的初始化记录
6. README.rst 已更新 - 提供了完整的安装和使用说明
7. GitHub Workflow 文件已生成 - loongsuite_lint_0.yml 和 loongsuite_test_0.yml 已创建

⚠️ 需要修复的问题

1. tox-loongsuite.ini 中 langchain 测试环境被注释

在 tox-loongsuite.ini 文件中，langchain 相关的测试环境被注释掉了：

; ; loongsuite-instrumentation-langchain
; py3{9,10,11,12,13}-test-loongsuite-instrumentation-langchain
; lint-loongsuite-instrumentation-langchain

这会导致 GitHub Actions 中的测试不会运行，需要取消注释。

2. util/opentelemetry-util-genai/handler.py 缺少 LoongSuite Extension 注释

根据审查规范，修改 util/opentelemetry-util-handler 中的特定文件（如 handler.py）时，需要在改动处添加 "LoongSuite Extension" 注释。但当前 handler.py 文件中没有看到相关注释。

📋 建议

1. 取消 tox-loongsuite.ini 中 langchain 测试环境的注释
2. 在 util/opentelemetry-util-genai/handler.py 的修改处添加 "LoongSuite Extension" 注释

🎯 总体评估

PR #133 基本符合 LoongSuite instrumentation 规范，主要问题在于测试配置和注释缺失。建议作者修复上述问题后再合并。

审查结论：需要修改后重新提交

[Cirilla-zmh]

PR #133 代码审查结果

✅ 符合规范的项目

1. pyproject.toml 配置正确 - 与其他同类 instrumentation 一致
2. 包含 version 文件 - 内容为 0.2.0.dev，符合开发版本规范
3. 包含 package 文件 - 正确设置了 langchain_core 依赖版本
4. LICENSE 文件头完整 - 所有文件都包含正确的 Apache 2.0 LICENSE 头
5. CHANGELOG 已更新 - 包含了 0.1.0 版本的初始化记录
6. README.md 已更新 - 提供了完整的安装和使用说明
7. GitHub Workflow 文件已生成 - loongsuite_lint_0.yml 和 loongsuite_test_0.yml 已创建

⚠️ 需要修复的问题

1. tox-loongsuite.ini 中 langchain 测试环境被注释

在 tox-loongsuite.ini 文件中，langchain 相关的测试环境被注释掉了（行 39-41）：

; ; loongsuite-instrumentation-langchain
; py3{9,10,11,12,13}-test-loongsuite-instrumentation-langchain
; lint-loongsuite-instrumentation-langchain

同时相关的依赖配置（行 100）和命令配置（行 150-151）也存在但被注释。

这会导致 GitHub Actions 中的测试不会运行，需要取消注释。

2. util/opentelemetry-util-genai/handler.py 缺少 LoongSuite Extension 注释

根据审查规范，修改 util/opentelemetry-util-handler 中的特定文件（如 handler.py）时，需要在改动处添加 "LoongSuite Extension" 注释。但当前 handler.py 文件中没有看到相关注释。

3. 确认没有多余的 LICENSE 文件

需要确认整个 PR 中没有在 instrumentation 目录下添加不必要的 LICENSE 文件。

🔍 潜在资源泄漏风险检查

从代码结构来看：

• 使用了 wrapt.wrap_function_wrapper 进行函数包装，这是安全的做法
• CallbackManager 的处理逻辑看起来合理，通过 add_handler 添加 tracer
• 没有明显的上下文泄漏或内存泄漏风险

📋 建议

1. 取消 tox-loongsuite.ini 中 langchain 测试环境的注释（行 39-41, 100, 150-151）
2. 在 util/opentelemetry-util-genai/handler.py 的修改处添加 "LoongSuite Extension" 注释
3. 确认没有多余的 LICENSE 文件

🎯 总体评估

PR #133 基本符合 LoongSuite instrumentation 规范，主要问题在于测试配置和注释缺失。建议作者修复上述问题后再合并。

审查结论：需要修改后重新提交

[Cirilla-zmh]

详细审查反馈 - 具体修改位置

🔧 需要修复的具体问题

1. tox-loongsuite.ini 中 langchain 测试环境被注释

文件:
行号: 39-41, 100, 150-151
问题: langchain 相关的测试环境配置被注释掉了，需要取消注释以确保 CI 能正常运行测试。

需要取消注释以下行：

• 行 39-41: 环境声明部分
• 行 100: 依赖配置
• 行 150-151: 命令配置

2. util/opentelemetry-util-genai/handler.py 缺少 LoongSuite Extension 注释

文件:
问题: 根据项目规范，修改 util 目录下的文件时需要在改动处添加 "LoongSuite Extension" 注释。请在相关修改位置添加此注释。

3. 确认没有多余的 LICENSE 文件

请检查整个 PR 变更，确保没有在 instrumentation 目录中添加不必要的 LICENSE 文件。

---

其他方面都符合规范！ 修复以上问题后就可以批准合并了。

[Cirilla-zmh]

注释格式不正确。应该使用 而不是 。请修正注释格式以保持一致性。

[Cirilla-zmh]

感谢提交 PR！我已经添加了两个行内评论，主要涉及：

1. tox-loongsuite.ini 注释格式问题：第 39 行的注释格式应该与其他 instrumentation 保持一致
2. tox-loongsuite.ini 依赖项命名一致性：第 100 行的环境名称应该使用 loongsuite-langchain-* 前缀以保持一致性

请修复这些问题后，我会重新审查并批准 PR。

[Copilot]

Pull request overview

Refactors LoongSuite LangChain instrumentation to a callback-based tracer architecture, extends opentelemetry-util-genai for explicit context propagation and safer context detachment, and adds LangGraph support for ReAct agent metadata propagation.

Changes:

• Added Entry (ENTRY) and ReAct Step (STEP) span support (types, attribute helpers, handler APIs, tests, docs).
• Introduced optional context parameter across start_* APIs and centralized safe context detachment via _safe_detach.
• Added new LangGraph instrumentation package + CI/tox matrices and a rewritten LangChain test suite.

Reviewed changes

Copilot reviewed 57 out of 58 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
util/opentelemetry-util-genai/tests/test_extended_handler.py	Adds tests for new Entry/ReAct Step handler APIs and baggage propagation.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py	Adds optional context for start_llm and introduces _safe_detach.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/extended_metrics.py	Extends metrics recorder typing to include Entry/ReAct Step invocations.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/extended_handler.py	Adds Entry/ReAct Step span lifecycle methods + context propagation across operations.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_multimodal_processing.py	Switches detach to _safe_detach in async multimodal pipeline.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_extended_semconv/gen_ai_extended_attributes.py	Adds semantic convention constants + new span kinds/operation names.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_extended_common/common_utils.py	Implements attribute application for Entry and ReAct Step spans.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_extended_common/common_types.py	Introduces EntryInvocation and ReactStepInvocation dataclasses.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_extended_common/init.py	Exposes new invocation types and helpers as a package API.
util/opentelemetry-util-genai/README-loongsuite.rst	Documents Entry and ReAct Step operations and baggage “traffic coloring”.
util/opentelemetry-util-genai/CHANGELOG-loongsuite.md	Changelog entries for Entry/ReAct Step + context param + _safe_detach change.
tox-loongsuite.ini	Adds langchain/langgraph oldest/latest env matrices and lint envs.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/tests/test_react_step_spans.py	Integration tests for LangGraph ReAct → LangChain tracer → OTel spans.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/tests/test_patch.py	Validates create_react_agent and Pregel.stream patching.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/tests/test_instrumentor.py	Adds basic lifecycle tests for the LangGraph instrumentor.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/tests/requirements.oldest.txt	Adds oldest dependency set for LangGraph instrumentation tests.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/tests/requirements.latest.txt	Adds latest dependency set for LangGraph instrumentation tests.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/tests/conftest.py	Shared OTel providers/fixtures and dual instrumentor setup for integration tests.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/tests/init.py	Adds package marker for LangGraph instrumentation tests.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/src/opentelemetry/instrumentation/langgraph/version.py	Introduces new package version module.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/src/opentelemetry/instrumentation/langgraph/package.py	Declares instrumented dependency and metrics support.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/src/opentelemetry/instrumentation/langgraph/internal/patch.py	Implements wrapt-based patching for ReAct metadata injection.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/src/opentelemetry/instrumentation/langgraph/internal/init.py	Adds package marker for internal patch module.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/src/opentelemetry/instrumentation/langgraph/init.py	Implements LangGraphInstrumentor instrument/uninstrument logic.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/pyproject.toml	Adds LangGraph instrumentation packaging metadata and entry point.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/README.md	Documents LangGraph instrumentation behavior and integration data flow.
instrumentation-loongsuite/loongsuite-instrumentation-langgraph/CHANGELOG.md	Adds initial changelog for the new LangGraph instrumentation package.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/test_tool_spans.py	Adds unit tests for tool span creation and content capture gating.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/test_retriever_spans.py	Adds unit tests for retriever span creation and content capture gating.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/test_react_step_patch.py	Tests AgentExecutor ReAct step patching and span creation.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/test_llm_spans.py	Adds LLM span tests (attrs/content capture/token usage/error status).
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/test_instrumentor.py	Adds lifecycle tests for wrapping/unwrapping callback manager init.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/test_data_extraction.py	Adds unit tests for new run/message extraction helpers.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/test_chain_spans.py	Adds chain span tests including input/output capture gating.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/test_basic.py	Adds end-to-end basic integration tests for span creation.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/test_agent_spans.py	Adds agent run-type detection tests.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/requirements.oldest.txt	Adds oldest dependency set for LangChain instrumentation tests.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/requirements.latest.txt	Adds latest dependency set for LangChain instrumentation tests.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/instrumentation/langchain/test_token_counts.py	Removes legacy token counting tests tied to old implementation.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/instrumentation/langchain/test_singleton_tracer.py	Removes legacy singleton tracer tests tied to old implementation.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/instrumentation/langchain/test_prompts.py	Removes legacy prompt parsing tests tied to old implementation.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/instrumentation/langchain/test_metadata.py	Removes legacy metadata tests tied to old implementation.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/instrumentation/langchain/test_message_parsing.py	Removes legacy message parsing tests tied to old implementation.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/instrumentation/langchain/test_langchain_instrumentor.py	Removes legacy large integration test suite (old wrapt-based approach).
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/conftest.py	Adds standardized pytest fixtures for providers/exporters and content modes.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/tests/init.py	Adds package marker for LangChain instrumentation tests.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/internal/semconv.py	Simplifies semconv to re-export util-genai semconv constants.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/internal/patch.py	Adds AgentExecutor step wrapper implementation.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/internal/_utils.py	Rewrites extraction utilities and adds LangGraph/agent detection helpers.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/init.py	Rewrites instrumentor lifecycle, adds AgentExecutor patching + unwrap on uninstrument.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/pyproject.toml	Updates packaging/deps to include util-genai and align supported versions.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/README.md	Updates installation and usage docs + traced operations matrix.
instrumentation-loongsuite/loongsuite-instrumentation-langchain/CHANGELOG.md	Adds changelog for rewrite, ReAct Step, and LangGraph agent support.
copilot-instructions.md	Adds style guidance for PLC0415 inline imports and naming conventions.
.github/workflows/loongsuite_test_0.yml	Adds CI jobs for langchain/langgraph oldest/latest across Python versions.
.github/workflows/loongsuite_lint_0.yml	Adds CI lint jobs for langchain/langgraph instrumentations.

Comments suppressed due to low confidence (6)

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_extended_common/common_utils.py:1

• invocation.attributes is applied last, which allows user-provided keys to overwrite required semantic convention fields like gen_ai.operation.name and gen_ai.span.kind. To keep spans semconv-compliant, consider either (a) applying invocation.attributes earlier and writing required attributes last, or (b) filtering out collisions (skip/rename user keys that overlap required keys).
  util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py:1
• _RUNTIME_CONTEXT is a private OpenTelemetry API and may change without notice across OTel releases. If the goal is to avoid the SDK's ERROR log, consider using only public APIs and suppressing/handling the exception at the call site (or switching to a documented hook/flag if one exists), so util-genai doesn’t depend on private internals.
  util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py:1
• _RUNTIME_CONTEXT is a private OpenTelemetry API and may change without notice across OTel releases. If the goal is to avoid the SDK's ERROR log, consider using only public APIs and suppressing/handling the exception at the call site (or switching to a documented hook/flag if one exists), so util-genai doesn’t depend on private internals.
  util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py:1
• _RUNTIME_CONTEXT is a private OpenTelemetry API and may change without notice across OTel releases. If the goal is to avoid the SDK's ERROR log, consider using only public APIs and suppressing/handling the exception at the call site (or switching to a documented hook/flag if one exists), so util-genai doesn’t depend on private internals.
  instrumentation-loongsuite/loongsuite-instrumentation-langgraph/src/opentelemetry/instrumentation/langgraph/init.py:1
• The project name appears as “LongSuite” here, while the repository/package naming elsewhere uses “LoongSuite”. Consider standardizing this string to “LoongSuite” for consistency across docs and module docstrings.
  util/opentelemetry-util-genai/src/opentelemetry/util/genai/extended_handler.py:1
• These are two separate imports from the same module and can be consolidated into a single import block. This reduces import noise and avoids triggering “reimported” style/lint rules in some configurations.

---

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

[Copilot]

The new _extract_token_usage only reads outputs["llm_output"].token_usage/usage and does not handle other common LangChain formats (e.g., generations[0][0].generation_info["token_usage"] or generations[0][0].message.response_metadata["token_usage"]). This will cause token usage attributes/metrics to be missing for providers that don't populate llm_output. Consider restoring the prior fallback logic and adding focused unit tests covering these formats.

[Copilot]

The README states Python >= 3.8, but pyproject.toml for loongsuite-instrumentation-langchain requires >=3.9. Please align the README requirement with the package metadata to avoid user confusion.

Suggested change

	- Python >= 3.8
	- Python >= 3.9