feat(javascript): Add Claude Code Agent SDK instrumentation #17844

codyde · 2025-10-01T21:09:45Z

Summary

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

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

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

Key Implementation Details

Why Not Automatic Like Other AI Integrations?

The Claude Code SDK (@anthropic-ai/claude-agent-sdk) is ESM-only with no CommonJS build, which prevents automatic instrumentation via OpenTelemetry's require() hooks that work for other integrations (Anthropic AI, OpenAI, etc.).

Solution: Helper Function Pattern

Provides createInstrumentedClaudeQuery() - a one-line helper that:

Lazy loads the SDK via dynamic import() (avoids bundler issues)
Automatically retrieves options from claudeCodeIntegration() config
Uses global singleton pattern (patches once, reuses everywhere)
Works with any bundler (Next.js/webpack, Vite, etc.)

Usage

// Step 1: Configure in Sentry init
import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: 'your-dsn',
  integrations: [
    Sentry.claudeCodeIntegration({
      recordInputs: true,
      recordOutputs: true
    })
  ],
});

// Step 2: Use in your code (1 line!)
import * as Sentry from '@sentry/node';

const query = Sentry.createInstrumentedClaudeQuery();

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

Remaining TODO's

Tests
Handle PII (disabling prompt transmission etc...)
Expanded JavaScript server SDKs

Adds Sentry tracing instrumentation for the @anthropic-ai/claude-agent-sdk following OpenTelemetry Semantic Conventions for Generative AI. Key features: - Captures agent invocation, LLM chat, and tool execution spans - Records token usage, model info, and session tracking - Supports input/output recording based on sendDefaultPii setting - Provides createInstrumentedClaudeQuery() helper for clean DX Due to ESM-only module constraints, this integration uses a helper function pattern instead of automatic OpenTelemetry instrumentation hooks. Usage: ```typescript import { createInstrumentedClaudeQuery } from '@sentry/node'; const query = createInstrumentedClaudeQuery(); ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

packages/node/src/integrations/tracing/claude-code/helpers.ts

… allow retry

…tring literal

…g in Claude Code integration - Add SEMANTIC_ATTRIBUTE_SENTRY_OP to all span creation calls (invoke_agent, chat, execute_tool) - Capture exceptions to Sentry in catch block with proper mechanism metadata - Ensure child spans (currentLLMSpan, previousLLMSpan) are always closed in finally block - Prevents incomplete traces if generator exits early

github-actions · 2025-10-01T23:51:52Z

size-limit report 📦

Path	Size	% Change	Change
@sentry/browser	24.23 kB	-	-
@sentry/browser - with treeshaking flags	22.75 kB	-	-
@sentry/browser (incl. Tracing)	40.42 kB	-	-
@sentry/browser (incl. Tracing, Replay)	78.8 kB	-	-
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	68.45 kB	-	-
@sentry/browser (incl. Tracing, Replay with Canvas)	83.47 kB	-	-
@sentry/browser (incl. Tracing, Replay, Feedback)	95.67 kB	-	-
@sentry/browser (incl. Feedback)	40.95 kB	-	-
@sentry/browser (incl. sendFeedback)	28.89 kB	-	-
@sentry/browser (incl. FeedbackAsync)	33.82 kB	-	-
@sentry/react	25.96 kB	-	-
@sentry/react (incl. Tracing)	42.39 kB	-	-
@sentry/vue	28.75 kB	-	-
@sentry/vue (incl. Tracing)	42.23 kB	-	-
@sentry/svelte	24.26 kB	-	-
CDN Bundle	25.75 kB	-	-
CDN Bundle (incl. Tracing)	40.31 kB	-	-
CDN Bundle (incl. Tracing, Replay)	76.55 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback)	82.06 kB	-	-
CDN Bundle - uncompressed	75.3 kB	-	-
CDN Bundle (incl. Tracing) - uncompressed	119.31 kB	-	-
CDN Bundle (incl. Tracing, Replay) - uncompressed	234.47 kB	-	-
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	247.23 kB	-	-
@sentry/nextjs (client)	44.4 kB	-	-
@sentry/sveltekit (client)	40.84 kB	-	-
@sentry/node-core	50.47 kB	-	-
@sentry/node	154.12 kB	+0.02%	+29 B 🔺
@sentry/node - without tracing	92.33 kB	-	-
@sentry/aws-serverless	106.03 kB	-	-

View base workflow run

github-actions · 2025-10-01T23:53:49Z

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	8,919	-	9,636	-7%
GET With Sentry	1,406	16%	1,444	-3%
GET With Sentry (error only)	6,110	69%	6,177	-1%
POST Baseline	1,202	-	1,179	+2%
POST With Sentry	525	44%	496	+6%
POST With Sentry (error only)	1,063	88%	1,022	+4%
MYSQL Baseline	3,345	-	3,310	+1%
MYSQL With Sentry	529	16%	375	+41%
MYSQL With Sentry (error only)	2,748	82%	2,658	+3%

View base workflow run

…t undefined

RulaKhaled · 2025-10-06T15:05:46Z

packages/node/src/integrations/tracing/claude-code/instrumentation.ts

+
+type ClaudeCodeInstrumentationOptions = ClaudeCodeOptions;
+
+const GEN_AI_ATTRIBUTES = {


We already have these attributes in packages/core/src/utils/ai/gen-ai-attributes.ts

RulaKhaled · 2025-10-06T15:06:31Z

packages/node/src/integrations/tracing/claude-code/instrumentation.ts

+
+const SENTRY_ORIGIN = 'auto.ai.claude-code';
+
+function setTokenUsageAttributes(


can you reuse function from packages/core/src/utils/ai/utils.ts?

RulaKhaled · 2025-10-06T15:07:35Z

packages/node/src/integrations/tracing/claude-code/instrumentation.ts

+    // Parse query arguments
+    const [queryParams] = args as [Record<string, unknown>];
+    const { options: queryOptions, inputMessages } = queryParams || {};
+    const model = (queryOptions as Record<string, unknown>)?.model ?? 'sonnet';


can we revert to unknown if not model found here? i think this might be confusing if it's not accurate

RulaKhaled · 2025-10-06T15:17:19Z

packages/node/src/integrations/tracing/claude-code/index.ts

+    name: CLAUDE_CODE_INTEGRATION_NAME,
+    options,
+    setupOnce() {
+      // Note: Automatic patching via require hooks doesn't work for ESM modules


actually i believe InstrumentationModuleDefinition will automatically patch Node.js modules when they're loaded via import, you can find some patterns in other AI integrations e.g anthropic AI

RulaKhaled · 2025-10-06T15:17:58Z

packages/node/src/integrations/tracing/claude-code/instrumentation.ts

+ * Patches the Claude Code SDK query function with Sentry instrumentation.
+ * This function can be called directly to patch an imported query function.
+ */
+export function patchClaudeCodeQuery(


We should hook into the query and use proxy here

RulaKhaled · 2025-10-06T15:18:19Z

packages/node/src/integrations/tracing/claude-code/instrumentation.ts

+    );
+
+    // Preserve Query interface methods
+    if (typeof (originalQueryInstance as Record<string, unknown>).interrupt === 'function') {


using proxy should clean this up a little

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 · 2025-10-06T17:48:41Z

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.

This comment was marked as outdated.

Sign in to view

seer-by-sentry bot reviewed Oct 1, 2025

View reviewed changes

packages/node/src/integrations/tracing/claude-code/helpers.ts Show resolved Hide resolved

fix(node): Reset init state on Claude Code instrumentation failure to…

6373d01

… allow retry

This comment was marked as outdated.

Sign in to view

fix(node): Use SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN constant instead of s…

e0e651b

…tring literal

This comment was marked as outdated.

Sign in to view

codyde marked this pull request as draft October 1, 2025 23:17

fix(node): Fix TypeScript types for createInstrumentedClaudeQuery

dbcf981

codyde added 3 commits October 1, 2025 17:09

feat(nextjs): Export Claude Code integration types

d0c2c3b

feat(nextjs): Add explicit runtime exports for Claude Code integration

dcc42a8

fix(nextjs): Import Claude Code exports before re-exporting to preven…

c897e76

…t undefined

codyde changed the title ~~feat(node): Add Claude Code Agent SDK instrumentation~~ feat(agent-monitoring): Add Claude Code Agent SDK instrumentation Oct 2, 2025

codyde changed the title ~~feat(agent-monitoring): Add Claude Code Agent SDK instrumentation~~ feat(javascript): Add Claude Code Agent SDK instrumentation Oct 2, 2025

RulaKhaled assigned RulaKhaled and unassigned RulaKhaled Oct 6, 2025

RulaKhaled self-requested a review October 6, 2025 08:17

RulaKhaled reviewed Oct 6, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(javascript): Add Claude Code Agent SDK instrumentation #17844

feat(javascript): Add Claude Code Agent SDK instrumentation #17844

Uh oh!

codyde commented Oct 1, 2025 •

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

github-actions bot commented Oct 1, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Oct 1, 2025 •

edited

Loading

Uh oh!

RulaKhaled Oct 6, 2025

Uh oh!

RulaKhaled Oct 6, 2025

Uh oh!

RulaKhaled Oct 6, 2025

Uh oh!

RulaKhaled Oct 6, 2025

Uh oh!

RulaKhaled Oct 6, 2025

Uh oh!

RulaKhaled Oct 6, 2025

Uh oh!

RulaKhaled left a comment •

edited

Loading

Uh oh!

codyde commented Oct 6, 2025

Uh oh!

Uh oh!


		type ClaudeCodeInstrumentationOptions = ClaudeCodeOptions;

		const GEN_AI_ATTRIBUTES = {


		const SENTRY_ORIGIN = 'auto.ai.claude-code';

		function setTokenUsageAttributes(

Uh oh!

feat(javascript): Add Claude Code Agent SDK instrumentation #17844

Are you sure you want to change the base?

feat(javascript): Add Claude Code Agent SDK instrumentation #17844

Uh oh!

Conversation

codyde commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Implementation Details

Why Not Automatic Like Other AI Integrations?

Solution: Helper Function Pattern

Usage

Remaining TODO's

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

github-actions bot commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

github-actions bot commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

node-overhead report 🧳

Uh oh!

RulaKhaled Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

RulaKhaled Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

RulaKhaled Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

RulaKhaled Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

RulaKhaled Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

RulaKhaled Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

RulaKhaled left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codyde commented Oct 6, 2025

Uh oh!

Uh oh!

codyde commented Oct 1, 2025 •

edited

Loading

github-actions bot commented Oct 1, 2025 •

edited

Loading

github-actions bot commented Oct 1, 2025 •

edited

Loading

RulaKhaled left a comment •

edited

Loading