feat(node): Add Claude Code Agent SDK instrumentation

[codyde]

Summary

Adds Sentry tracing instrumentation for the @anthropic-ai/claude-agent-sdk (Claude Code Agent SDK) following OpenTelemetry Semantic Conventions for Generative AI.

This integration enables AI monitoring for Claude Code agents with comprehensive telemetry:

• Agent invocation spans (gen_ai.invoke_agent)
• LLM chat spans (gen_ai.chat)
• Tool execution spans (gen_ai.execute_tool)
• Token usage tracking (including cache metrics)
• Model info and session tracking
• Optional input/output recording (respects sendDefaultPii)

Implementation

Uses automatic OpenTelemetry instrumentation via import-in-the-middle hooks - the same pattern as other AI integrations (Anthropic, OpenAI, Vercel AI, etc.). When the integration is added, it automatically patches the query function from @anthropic-ai/claude-agent-sdk.

Important: Sentry must be initialized before importing @anthropic-ai/claude-agent-sdk for auto-instrumentation to work.

Usage

// Initialize Sentry FIRST
import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: 'your-dsn',
  integrations: [
    Sentry.claudeCodeAgentSdkIntegration({
      recordInputs: true,
      recordOutputs: true,
      agentName: 'my-coding-assistant', // optional
    }),
  ],
});

// THEN import the SDK - it will be automatically instrumented!
import { query } from '@anthropic-ai/claude-agent-sdk';

// Use query as normal - spans are created automatically
for await (const message of query({
  prompt: 'Hello',
  options: { model: 'claude-sonnet-4-20250514' },
})) {
  console.log(message);
}

Options

Option	Type	Default	Description
recordInputs	boolean	sendDefaultPii	Whether to record prompt messages
recordOutputs	boolean	sendDefaultPii	Whether to record response text, tool calls, and outputs
agentName	string	'claude-code'	Custom agent name for span identification

Captured Telemetry

Span Hierarchy

invoke_agent claude-code
├── chat claude-sonnet-4-20250514
│   └── execute_tool Read
│   └── execute_tool Bash
├── chat claude-sonnet-4-20250514
│   └── execute_tool WebSearch
└── ...

Attributes (OpenTelemetry GenAI Semantic Conventions)

• gen_ai.system: anthropic
• gen_ai.operation.name: invoke_agent | chat | execute_tool
• gen_ai.agent.name: Custom or claude-code
• gen_ai.request.model: Model identifier
• gen_ai.request.available_tools: Available tools from system init
• gen_ai.response.id: Response/session ID
• gen_ai.response.model: Actual model used
• gen_ai.response.finish_reasons: Stop reason
• gen_ai.response.text: Response text (when recordOutputs: true)
• gen_ai.response.tool_calls: Tool calls made (when recordOutputs: true)
• gen_ai.tool.name: Tool name (e.g., Read, Bash, WebSearch)
• gen_ai.tool.type: function | extension | datastore
• gen_ai.tool.input: Tool input (when recordInputs: true)
• gen_ai.tool.output: Tool output (when recordOutputs: true)
• gen_ai.usage.input_tokens: Input token count
• gen_ai.usage.output_tokens: Output token count
• gen_ai.usage.cache_creation_input_tokens: Cache creation tokens
• gen_ai.usage.cache_read_input_tokens: Cache read tokens

Tool Type Classification

• Function tools (client-side execution): Bash, Read, Write, Edit, Glob, Grep, Task, TodoWrite, NotebookEdit, SlashCommand, AskUserQuestion, Skill, etc.
• Extension tools (external APIs): WebSearch, WebFetch, ListMcpResources, ReadMcpResource

Manual Instrumentation

For advanced use cases where auto-instrumentation is not suitable, patchClaudeCodeQuery is exported for manual patching:

import { patchClaudeCodeQuery } from '@sentry/node';
import { query } from '@anthropic-ai/claude-agent-sdk';

const instrumentedQuery = patchClaudeCodeQuery(query, {
  recordInputs: true,
  recordOutputs: true,
  agentName: 'my-agent',
});

Testing

Includes comprehensive integration tests covering:

• Basic agent invocation with default PII settings
• Input/output recording with sendDefaultPii: true
• Custom recordInputs/recordOutputs options
• Tool execution spans (function and extension types)
• Error handling and span status

[github-actions]

size-limit report 📦

Path	Size	% Change	Change
@sentry/browser	25.05 kB	-	-
@sentry/browser - with treeshaking flags	23.58 kB	-	-
@sentry/browser (incl. Tracing)	41.8 kB	-	-
@sentry/browser (incl. Tracing, Profiling)	46.38 kB	-	-
@sentry/browser (incl. Tracing, Replay)	80.41 kB	-	-
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	70.12 kB	-	-
@sentry/browser (incl. Tracing, Replay with Canvas)	85.11 kB	-	-
@sentry/browser (incl. Tracing, Replay, Feedback)	97.31 kB	-	-
@sentry/browser (incl. Feedback)	41.77 kB	-	-
@sentry/browser (incl. sendFeedback)	29.73 kB	-	-
@sentry/browser (incl. FeedbackAsync)	34.73 kB	-	-
@sentry/browser (incl. Metrics)	26.16 kB	-	-
@sentry/browser (incl. Logs)	26.3 kB	-	-
@sentry/browser (incl. Metrics & Logs)	26.96 kB	-	-
@sentry/react	26.78 kB	-	-
@sentry/react (incl. Tracing)	44.02 kB	+0.01%	+3 B 🔺
@sentry/vue	29.5 kB	-	-
@sentry/vue (incl. Tracing)	43.6 kB	-	-
@sentry/svelte	25.06 kB	-	-
CDN Bundle	27.57 kB	-	-
CDN Bundle (incl. Tracing)	42.56 kB	-	-
CDN Bundle (incl. Tracing, Replay)	79.26 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback)	84.68 kB	-	-
CDN Bundle - uncompressed	80.82 kB	-	-
CDN Bundle (incl. Tracing) - uncompressed	126.2 kB	-	-
CDN Bundle (incl. Tracing, Replay) - uncompressed	242.74 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	255.53 kB	-	-
@sentry/nextjs (client)	46.37 kB	-	-
@sentry/sveltekit (client)	42.18 kB	-	-
@sentry/node-core	51.86 kB	-	-
⛔️ @sentry/node (max: 163 kB)	163.67 kB	+0.97%	+1.57 kB 🔺
@sentry/node - without tracing	93.29 kB	-	-
@sentry/aws-serverless	108.78 kB	-	-

View base workflow run

[github-actions]

node-overhead report 🧳

Note: This is a synthetic benchmark with a minimal express app and does not necessarily reflect the real-world performance impact in an application.

Scenario	Requests/s	% of Baseline	Prev. Requests/s	Change %
GET Baseline	9,399	-	8,758	+7%
GET With Sentry	1,768	19%	1,683	+5%
GET With Sentry (error only)	6,160	66%	6,037	+2%
POST Baseline	1,203	-	1,182	+2%
POST With Sentry	596	50%	576	+3%
POST With Sentry (error only)	1,072	89%	1,047	+2%
MYSQL Baseline	3,348	-	3,207	+4%
MYSQL With Sentry	491	15%	407	+21%
MYSQL With Sentry (error only)	2,719	81%	2,615	+4%

View base workflow run

[RulaKhaled]

Thanks for working on this! For the first pass, the biggest lift here is to try to auto patch the functions we need automatically instead of asking user to import patched method, then we can move to tackling the other TODOs you have

[codyde]

Thanks for working on this! For the first pass, the biggest lift here is to try to auto patch the functions we need automatically instead of asking user to import patched method, then we can move to tackling the other TODOs you have

Thanks SO much for all these. I'll get started on them.

I tried REALLY hard to figure out how to hook into the existing query, and I couldn't get it to work no matter what I tried. I'll chat with you in slack on it, but I'd love some advice / guidance. I tried a bunch of different angles - but each time I ran into effectively timing issues where we couldn't hook fast enough. Felt like a limitation on how Claude Code's SDK works - but could be a total skill issue on my side.

[RulaKhaled]

Thanks for working on this! For the first pass, the biggest lift here is to try to auto patch the functions we need automatically instead of asking user to import patched method, then we can move to tackling the other TODOs you have

Thanks SO much for all these. I'll get started on them.

I tried REALLY hard to figure out how to hook into the existing query, and I couldn't get it to work no matter what I tried. I'll chat with you in slack on it, but I'd love some advice / guidance. I tried a bunch of different angles - but each time I ran into effectively timing issues where we couldn't hook fast enough. Felt like a limitation on how Claude Code's SDK works - but could be a total skill issue on my side.

Hello @codyde, are you still working on this? if not, let's close this, we're trying to clean up the stale PRs

[codyde]

Thanks for working on this! For the first pass, the biggest lift here is to try to auto patch the functions we need automatically instead of asking user to import patched method, then we can move to tackling the other TODOs you have

Thanks SO much for all these. I'll get started on them.
I tried REALLY hard to figure out how to hook into the existing query, and I couldn't get it to work no matter what I tried. I'll chat with you in slack on it, but I'd love some advice / guidance. I tried a bunch of different angles - but each time I ran into effectively timing issues where we couldn't hook fast enough. Felt like a limitation on how Claude Code's SDK works - but could be a total skill issue on my side.

Hello @codyde, are you still working on this? if not, let's close this, we're trying to clean up the stale PRs

I definitely am! I pushed up a few more commits today that included fixes for some of the other items you mentioned - but im struggling to get through this proxy one. I might need some pairing time to take a look at it together since im less familiar with the functionality.

[RulaKhaled]

This looks a lot better! Thank you :)

I’ve left some comments, and I’ll continue the review next week—mainly to make sure we’re not missing any attributes and that the tests are passing. We’re so close to getting this in.

[codyde]

Accidental comment

[RulaKhaled]

Ok can we fix lint issues/tests and resolve cursor comments? Meanwhile I will be testing this locally with both esm/cjs

[cursor]

LLM spans get ended twice with multiple assistant messages

Low Severity

When handling multiple assistant messages, previousLLMSpan is assigned a span that was already ended on line 283-286. Then when the result message handler or next assistant message handler runs, it calls setStatus() and end() on previousLLMSpan without checking if the span is still recording. The finally block correctly uses isRecording() before ending spans, but the main flow at lines 245-250 and 385-391 lacks this check. This causes setStatus() and end() to be called on already-ended spans. While OpenTelemetry likely treats this as a no-op, it's inconsistent with the pattern used in the finally block and indicates a state management issue.

Additional Locations (1)

• packages/node/src/integrations/tracing/claude-code/helpers.ts#L244-L250

 

[codyde]

Fixed in commit db79f79 - Added isRecording() checks before calling setStatus() and end() on previousLLMSpan in both the assistant message handler (line 245) and result message handler (line 385). This matches the pattern used in the finally block and prevents operations on already-ended spans.