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.2 kB	-	-
@sentry/browser - with treeshaking flags	23.71 kB	-	-
@sentry/browser (incl. Tracing)	42.02 kB	-	-
@sentry/browser (incl. Tracing, Profiling)	46.66 kB	-	-
@sentry/browser (incl. Tracing, Replay)	80.63 kB	-	-
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	70.28 kB	-	-
@sentry/browser (incl. Tracing, Replay with Canvas)	85.32 kB	-	-
@sentry/browser (incl. Tracing, Replay, Feedback)	97.53 kB	-	-
@sentry/browser (incl. Feedback)	41.92 kB	-	-
@sentry/browser (incl. sendFeedback)	29.89 kB	-	-
@sentry/browser (incl. FeedbackAsync)	34.89 kB	-	-
@sentry/browser (incl. Metrics)	26.31 kB	-	-
@sentry/browser (incl. Logs)	26.46 kB	-	-
@sentry/browser (incl. Metrics & Logs)	27.11 kB	-	-
@sentry/react	26.93 kB	-	-
@sentry/react (incl. Tracing)	44.26 kB	-	-
@sentry/vue	29.64 kB	-	-
@sentry/vue (incl. Tracing)	43.82 kB	-	-
@sentry/svelte	25.22 kB	-	-
CDN Bundle	27.78 kB	-	-
CDN Bundle (incl. Tracing)	42.83 kB	-	-
CDN Bundle (incl. Tracing, Logs, Metrics)	43.65 kB	-	-
CDN Bundle (incl. Tracing, Replay)	79.53 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback)	84.97 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics)	85.89 kB	-	-
CDN Bundle - uncompressed	81.27 kB	-	-
CDN Bundle (incl. Tracing) - uncompressed	126.81 kB	-	-
CDN Bundle (incl. Tracing, Logs, Metrics) - uncompressed	129.65 kB	-	-
CDN Bundle (incl. Tracing, Replay) - uncompressed	243.35 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	256.15 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) - uncompressed	258.96 kB	-	-
@sentry/nextjs (client)	46.62 kB	-	-
@sentry/sveltekit (client)	42.39 kB	-	-
@sentry/node-core	51.9 kB	-	-
@sentry/node	166.93 kB	+0.9%	+1.48 kB 🔺
@sentry/node - without tracing	93.66 kB	-	-
@sentry/aws-serverless	109.16 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	11,409	-	8,944	+28%
GET With Sentry	1,913	17%	1,786	+7%
GET With Sentry (error only)	7,576	66%	6,223	+22%
POST Baseline	1,164	-	1,206	-3%
POST With Sentry	577	50%	597	-3%
POST With Sentry (error only)	1,025	88%	1,064	-4%
MYSQL Baseline	3,972	-	3,304	+20%
MYSQL With Sentry	463	12%	513	-10%
MYSQL With Sentry (error only)	3,277	83%	2,667	+23%

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]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}