feat: add OpenTelemetry tracing support#530
Draft
wingding12 wants to merge 1 commit intoanthropics:mainfrom
Draft
feat: add OpenTelemetry tracing support#530wingding12 wants to merge 1 commit intoanthropics:mainfrom
wingding12 wants to merge 1 commit intoanthropics:mainfrom
Conversation
Add opt-in OpenTelemetry tracing via the `tracer` parameter in
ClaudeAgentOptions. When a tracer is provided, spans are created for
key operations:
- claude_agent_sdk.query - for query() function calls
- claude_agent_sdk.session - for ClaudeSDKClient sessions
- claude_agent_sdk.control - for control protocol requests
- claude_agent_sdk.permission - for tool permission checks
- claude_agent_sdk.hook - for hook callbacks
- claude_agent_sdk.mcp - for MCP server requests
Usage:
```python
from opentelemetry import trace
tracer = trace.get_tracer("my-app")
options = ClaudeAgentOptions(tracer=tracer)
```
Install with: pip install claude-agent-sdk[telemetry]
Closes anthropics#452
qing-ant
added a commit
that referenced
this pull request
Apr 16, 2026
## What
If the SDK caller has an active OpenTelemetry span, inject its W3C trace
context into the CLI subprocess env as `TRACEPARENT`/`TRACESTATE`. The
CLI reads these in headless mode and parents its
`claude_code.interaction` spans under the caller's distributed trace.
- Optional: `pip install claude-agent-sdk[otel]` pulls
`opentelemetry-api`. Gracefully no-ops if not installed.
- `setdefault` so `ClaudeAgentOptions(env={"TRACEPARENT": ...})` wins.
## Why
Agent SDK customers see CLI traces as disconnected roots in their
collector. This is the minimal change to enable distributed tracing
end-to-end without adding a `tracer` option (consistent with the
env-var-only config decision).
Relates to #452. This PR does not add in-process SDK spans (#530/#542) —
only context propagation to the CLI.
## Requires
`claude` CLI **≥ v2.1.110** for the propagation to take effect — earlier
versions ignore `TRACEPARENT` (harmless no-op, spans just stay as
roots).
## Proof
- `pytest tests/test_transport.py` — 62 pass (3 new)
- `ruff check` / `ruff format --check` / `mypy src/` — clean
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add opt-in OpenTelemetry tracing support via the
tracerparameter inClaudeAgentOptions. This enables observability for applications using the Claude SDK.Changes
tracerparameter toClaudeAgentOptionsTracingContextclass and span utilitiesClaudeSDKClienttelemetryoptional dependency (opentelemetry-api>=1.20.0)Span Names
When tracing is enabled, the following spans are created:
claude_agent_sdk.queryclaude_agent_sdk.sessionclaude_agent_sdk.controlclaude_agent_sdk.permissionclaude_agent_sdk.hookclaude_agent_sdk.mcpUsage
Install with:
pip install claude-agent-sdk[telemetry]Test Plan
Closes #452