feat(claude-agent-sdk): add instrumentation for @anthropic-ai/claude-agent-sdk#7603
Open
mr-lee wants to merge 1 commit intoDataDog:masterfrom
Open
feat(claude-agent-sdk): add instrumentation for @anthropic-ai/claude-agent-sdk#7603mr-lee wants to merge 1 commit intoDataDog:masterfrom
mr-lee wants to merge 1 commit intoDataDog:masterfrom
Conversation
mr-lee
force-pushed
the
feat/claude-agent-sdk-integration
branch
3 times, most recently
from
ca06588 to
0b55aab
Compare
mr-lee
force-pushed
the
feat/claude-agent-sdk-integration
branch
2 times, most recently
from
6e28bea to
ddaa3f1
Compare
wconti27
added
the
AI Generated
|
this would be really great, but much less useful without individual llm call spans bc that is where cost estimates come from |
Member
|
It seems like this is in your wheelhouse @sabrenner |
Collaborator
|
@tlhunter yep, will be taking a look at this PR throughout the next week (we're aligning on some things internally) |
Member
|
@mr-lee could you please rebase and fix reported lint issues already? :) |
mr-lee
force-pushed
the
feat/claude-agent-sdk-integration
branch
from
e0cf971 to
65d163b
Compare
mr-lee
force-pushed
the
feat/claude-agent-sdk-integration
branch
2 times, most recently
from
d65cfaf to
f90a168
Compare
…agent-sdk
Adds automatic instrumentation for the Claude Agent SDK, providing
full visibility into agentic sessions via APM tracing and LLM Obs.
Span hierarchy aligned with trajectory-spec APPENDIX-DD-LLMOBS-MAPPING:
agent (session)
└── agent (turn)
├── tool ({tool_name})
└── agent (subagent-{agent_type})
Key design decisions:
- Uses SDK's first-class hooks API (SessionStart, SessionEnd, Stop,
PreToolUse, PostToolUse, SubagentStart, SubagentStop, etc.)
- Turn spans are `agent` kind (not workflow) per spec
- Dynamic span names: session, turn, {toolName}, subagent-{type}
- Model name split from provider prefix (anthropic/claude-sonnet-4-6)
- Turn output from Stop hook's last_assistant_message
- Captures cwd, transcript_path, agent_type, is_interrupt, start_trigger
- Pure ESM package handled via import-in-the-middle with esmFirst: true
- User hooks preserved via mergeHooks (user matchers before tracer matchers)
Known gap: No LLM-level spans - the Agent SDK bundles its own Anthropic
client internally, so the existing @anthropic-ai/sdk shimmer doesn't fire.
This matches dd-trace-py's approach (agent + tool spans only).
Tests: 41 APM tracing + 13 LLM Obs tests.
mr-lee
force-pushed
the
feat/claude-agent-sdk-integration
branch
from
f90a168 to
c17d0d8
Compare
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
6 participants
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
Adds automatic instrumentation for the Claude Agent SDK (
@anthropic-ai/claude-agent-sdk), providing full visibility into agentic sessions via APM tracing and LLM Observability.Span hierarchy
Key design decisions
SessionStart,SessionEnd,Stop,PreToolUse,PostToolUse,SubagentStart,SubagentStop, etc.) — not monkey-patching internalsagentkind (notworkflow) — turns are complete agentic response cyclessession,turn,{toolName},subagent-{agentType}instead of static prefixed namesanthropic/claude-sonnet-4-6→model_name: claude-sonnet-4-6,model_provider: anthropiclast_assistant_messagefrom SDK'sStophook (the final agent text for each turn)start_trigger,project_dir,exit_reason,transcript_path,agent_type,is_interruptmergeHooks(user matchers placed before tracer matchers)import-in-the-middlewithesmFirst: trueKnown gap
No LLM-level spans — the Agent SDK bundles its own Anthropic client internally (never imports
@anthropic-ai/sdk), so the existing Anthropic shimmer doesn't fire. This matches dd-trace-py's approach: agent + tool spans only, with token metrics aggregated on the agent span fromResultMessage.Performance
~186μs overhead per session (10 spans, 22 hook invocations), ~18μs per span. Negligible vs real
query()calls.Test plan
claude-agent-sdkjob passes on Node 18 + latest