feat: Add instrumentation for claude agent sdk #103 #104

sipercai · 2026-01-09T03:04:21Z

Description

This PR adds OpenTelemetry instrumentation support for Claude Agent SDK, enabling automatic tracing and metrics collection for Claude agent conversations, LLM calls, and tool executions.

Fixes #103

Type of change

New feature (non-breaking change which adds functionality)
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

Test

Lint check

tox -c tox-loongsuite.ini -e lint-loongsuite-instrumentation-claude-agent-sdk

Unit tests (Python 3.12 + latest)

tox -c tox-loongsuite.ini -e py312-test-loongsuite-instrumentation-claude-agent-sdk-latest

Does This PR Require a Core Repo Change?

Yes. - Link to PR:
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

- Initial implementation of Claude Agent SDK instrumentation - Support for agent query sessions via Hooks mechanism - Support for tool execution tracing (PreToolUse/PostToolUse hooks) - Integration with opentelemetry-util-genai ExtendedTelemetryHandler - Span attributes following OpenTelemetry GenAI Semantic Conventions - Support for Alibaba Cloud DashScope Anthropic-compatible API Change-Id: aebd1fd0-3afc-4a37-af74-3800c117aaf0 Change-Id: I187974bfe8b44b9f592ffcb368e11d98c41f1a30 Co-developed-by: Cursor <[email protected]>

Change-Id: Ie6eab7ffae40e000b3b2c55a0abe50848490c1e7 Co-developed-by: Cursor <[email protected]>

Change-Id: I2656979e57ed2e9b3110867f9e5f6321d45cb3e2 Co-developed-by: Cursor <[email protected]>

Change-Id: Ibf6f934583ed0e76a4f79016cbfbade94a05acec Co-developed-by: Cursor <[email protected]>

Change-Id: I1420318408a53e563499c43a3cc2ae86ed0aa929 Co-developed-by: Cursor <[email protected]>

Change-Id: Iab09e483df20ef8ad44545e36d0d83f5ae0cae1d Co-developed-by: Cursor <[email protected]>

Change-Id: I55134f7e3ef30b7192deab801b12b132b250a31c Co-developed-by: Cursor <[email protected]>

Change-Id: I44bf3572fa7d8bf7d47b665d3463433a93076f9c Co-developed-by: Cursor <[email protected]>

Change-Id: I4308f8d8ecc7048c1bc9d1d9ec824addad1c5912 Co-developed-by: Cursor <[email protected]>

Change-Id: Ice677164663bc066e830b3cd24c09697d2dd0fb1 Co-developed-by: Cursor <[email protected]>

Change-Id: Ieadc2e7ea2193e301c171c62eee9da3179c95199 Co-developed-by: Cursor <[email protected]>

Copilot

Pull request overview

This PR adds OpenTelemetry instrumentation for the Claude Agent SDK, enabling automatic tracing and metrics collection for Claude agent conversations, LLM calls, and tool executions. The implementation introduces a new instrumentation package that follows OpenTelemetry GenAI semantic conventions.

Changes:

Adds comprehensive instrumentation for Claude Agent SDK including agent sessions, tool executions, and token tracking
Implements test suites covering unit tests, integration tests, edge cases, and attribute validation
Configures CI/CD workflows for automated testing and linting across multiple Python versions

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tox-loongsuite.ini	Adds tox environment configuration for claude-agent-sdk instrumentation testing
.github/workflows/loongsuite_test_0.yml	Adds CI test jobs for Python 3.10-3.13 across oldest/latest dependency versions
.github/workflows/loongsuite_lint_0.yml	Adds linting job for claude-agent-sdk instrumentation
util/opentelemetry-util-genai/.../pre_uploader.py	Adds pyright ignore comment for numpy import
instrumentation-loongsuite/loongsuite-instrumentation-claude-agent-sdk/*	New instrumentation package with source code, tests, and documentation

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

Copilot · 2026-01-15T05:58:22Z

...instrumentation-claude-agent-sdk/src/opentelemetry/instrumentation/claude_agent_sdk/patch.py

+        # Override span start time
+        if llm_invocation.span and start_time:
+            start_time_ns = int(start_time * 1_000_000_000)
+            try:
+                if hasattr(llm_invocation.span, "_start_time"):
+                    llm_invocation.span._start_time = start_time_ns  # type: ignore


Accessing private attribute _start_time directly is fragile and violates encapsulation. This implementation relies on internal implementation details of the span object that may change. Consider using a public API if available, or document this as a known technical debt with a TODO comment explaining why this is necessary and what the proper solution would be.

Suggested change

# Override span start time

if llm_invocation.span and start_time:

start_time_ns = int(start_time * 1_000_000_000)

try:

if hasattr(llm_invocation.span, "_start_time"):

llm_invocation.span._start_time = start_time_ns # type: ignore

# Override span start time.

# TODO(telemetry): Avoid relying on the private `_start_time` attribute.

# The long-term fix is to plumb a public `start_time` parameter through

# ExtendedTelemetryHandler.start_llm and the underlying span creation,

# so the desired start time can be set via a supported API instead of

# mutating internal span state here. Until that is available, we perform

# a best-effort adjustment guarded by hasattr and try/except so that

# failures do not break tracing.

if llm_invocation.span and start_time:

start_time_ns = int(start_time * 1_000_000_000)

try:

if hasattr(llm_invocation.span, "_start_time"):

setattr( # type: ignore[attr-defined]

llm_invocation.span, "_start_time", start_time_ns

)

Copilot · 2026-01-15T05:58:23Z

...instrumentation-claude-agent-sdk/src/opentelemetry/instrumentation/claude_agent_sdk/hooks.py

+                    type=RuntimeError,
+                ),
+            )
+        except Exception:


'except' clause does nothing but pass and there is no explanatory comment.

Copilot · 2026-01-15T05:58:23Z

...instrumentation-claude-agent-sdk/src/opentelemetry/instrumentation/claude_agent_sdk/hooks.py

+                    type=RuntimeError,
+                ),
+            )
+        except Exception:


'except' clause does nothing but pass and there is no explanatory comment.

Copilot · 2026-01-15T05:58:23Z

instrumentation-loongsuite/loongsuite-instrumentation-claude-agent-sdk/tests/test_edge_cases.py

+            count += 1
+            if count > 5:  # Prevent infinite loop
+                break
+    except Exception:


'except' clause does nothing but pass and there is no explanatory comment.

Suggested change

except Exception:

except Exception:

# Ignore exceptions here; this test only verifies that instrumentation

# can handle an empty prompt without crashing the test suite.

sipercai added 3 commits January 9, 2026 10:25

[fix] Require Python >=3.10 and fix test deps

0f26754

Change-Id: Ie6eab7ffae40e000b3b2c55a0abe50848490c1e7 Co-developed-by: Cursor <[email protected]>

[fix] Remove version constraint from opentelemetry-util-genai dependency

c9d1396

Change-Id: I2656979e57ed2e9b3110867f9e5f6321d45cb3e2 Co-developed-by: Cursor <[email protected]>

github-actions bot assigned 123liuziming, Cirilla-zmh and ralf0131 Jan 9, 2026

github-actions bot requested review from 123liuziming, Cirilla-zmh and ralf0131 January 9, 2026 03:04

sipercai added 3 commits January 9, 2026 11:20

[fix] fix test failed

589ada2

Change-Id: Ibf6f934583ed0e76a4f79016cbfbade94a05acec Co-developed-by: Cursor <[email protected]>

[fix] fix test failed

9fbf954

Change-Id: I1420318408a53e563499c43a3cc2ae86ed0aa929 Co-developed-by: Cursor <[email protected]>

[fix] fix ruff failed

462b1a0

Change-Id: Iab09e483df20ef8ad44545e36d0d83f5ae0cae1d Co-developed-by: Cursor <[email protected]>

sipercai force-pushed the liuyu/claude-clean branch from c3e3afb to 462b1a0 Compare January 9, 2026 03:39

sipercai and others added 6 commits January 9, 2026 14:06

[fix]:fix llm span time record error

5f317f9

Change-Id: I55134f7e3ef30b7192deab801b12b132b250a31c Co-developed-by: Cursor <[email protected]>

[fix]:fix agent context error

96e375f

Change-Id: I44bf3572fa7d8bf7d47b665d3463433a93076f9c Co-developed-by: Cursor <[email protected]>

Merge branch 'alibaba:main' into liuyu/claude-clean

c31b9ff

[fix] fix handler reset and model fallback

cb87246

Change-Id: I4308f8d8ecc7048c1bc9d1d9ec824addad1c5912 Co-developed-by: Cursor <[email protected]>

[fix] fix tool call status

9f42fcc

Change-Id: Ice677164663bc066e830b3cd24c09697d2dd0fb1 Co-developed-by: Cursor <[email protected]>

[fix] fix test error

c38bdcd

Change-Id: Ieadc2e7ea2193e301c171c62eee9da3179c95199 Co-developed-by: Cursor <[email protected]>

sipercai force-pushed the liuyu/claude-clean branch from a3b3f65 to c38bdcd Compare January 12, 2026 06:17

ralf0131 requested a review from Copilot January 15, 2026 05:54

Copilot started reviewing on behalf of ralf0131 January 15, 2026 05:54 View session

Copilot AI reviewed Jan 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add instrumentation for claude agent sdk #103 #104

feat: Add instrumentation for claude agent sdk #103 #104

Uh oh!

sipercai commented Jan 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 15, 2026

Uh oh!

Copilot AI Jan 15, 2026

Uh oh!

Copilot AI Jan 15, 2026

Uh oh!

Copilot AI Jan 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

-        # Override span start time
-        if llm_invocation.span and start_time:
-            start_time_ns = int(start_time * 1_000_000_000)
-            try:
-                if hasattr(llm_invocation.span, "_start_time"):
-                    llm_invocation.span._start_time = start_time_ns  # type: ignore
+        # Override span start time.
+        # TODO(telemetry): Avoid relying on the private `_start_time` attribute.
+        # The long-term fix is to plumb a public `start_time` parameter through
+        # ExtendedTelemetryHandler.start_llm and the underlying span creation,
+        # so the desired start time can be set via a supported API instead of
+        # mutating internal span state here. Until that is available, we perform
+        # a best-effort adjustment guarded by hasattr and try/except so that
+        # failures do not break tracing.
+        if llm_invocation.span and start_time:
+            start_time_ns = int(start_time * 1_000_000_000)
+            try:
+                if hasattr(llm_invocation.span, "_start_time"):
+                    setattr(  # type: ignore[attr-defined]
+                        llm_invocation.span, "_start_time", start_time_ns
+                    )

feat: Add instrumentation for claude agent sdk #103 #104

Are you sure you want to change the base?

feat: Add instrumentation for claude agent sdk #103 #104

Uh oh!

Conversation

sipercai commented Jan 9, 2026

Description

Type of change

How Has This Been Tested?

Lint check

Unit tests (Python 3.12 + latest)

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!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants