feat(claude-agent-sdk): add instrumentation for @anthropic-ai/claude-agent-sdk

.github/workflows/llmobs.yml

@@ -248,6 +248,39 @@ jobs:
         with:
           dd_api_key: ${{ steps.dd-sts.outputs.api_key }}
 
+  claude-agent-sdk:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    env:
+      PLUGINS: claude-agent-sdk
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: ./.github/actions/dd-sts-api-key
+        id: dd-sts
+      - uses: ./.github/actions/testagent/start
+      - uses: ./.github/actions/node/oldest-maintenance-lts
+      - uses: ./.github/actions/install
+      - run: yarn test:plugins:ci
+      - run: yarn test:llmobs:plugins:ci
+        shell: bash
+      - uses: ./.github/actions/node/latest
+      - run: yarn test:plugins:ci
+      - run: yarn test:llmobs:plugins:ci
+        shell: bash
+      - uses: ./.github/actions/coverage
+        with:
+          flags: llmobs-${{ github.job }}
+          dd_api_key: ${{ steps.dd-sts.outputs.api_key }}
+      - if: always()
+        uses: ./.github/actions/testagent/logs
+        with:
+          suffix: llmobs-${{ github.job }}
+      - uses: ./.github/actions/push_to_test_optimization
+        if: "!cancelled()"
+        with:
+          dd_api_key: ${{ steps.dd-sts.outputs.api_key }}
+
   google-genai:
     runs-on: ubuntu-latest
     permissions:

benchmark/sirun/plugin-claude-agent-sdk/README.md

@@ -0,0 +1,3 @@
+Simulates 500 agent sessions, each with 3 turns and 2 tool calls per turn
+(22 hook invocations per session). Measures the overhead of the shimmer's
+hook injection, diagnostics channel publishing, and span creation/finishing.

benchmark/sirun/plugin-claude-agent-sdk/index.js

@@ -0,0 +1,67 @@
+'use strict'
+
+if (Number(process.env.USE_TRACER)) {
+  require('../../..').init()
+
+  // Simulate SDK module load so the plugin manager activates channel
+  // subscriptions (same event that fires when the real ESM SDK is loaded).
+  const { channel } = require('dc-polyfill')
+  channel('dd-trace:instrumentation:load').publish({ name: '@anthropic-ai/claude-agent-sdk' })
+}
+
+const { wrapQuery } = require('../../../packages/datadog-instrumentations/src/claude-agent-sdk')
+
+const SESSIONS = 500
+
+// Simulate the SDK calling registered hooks, matching the real SDK's
+// matcher-array contract: each event is an array of matchers, each
+// matcher has an array of hook functions.
+function callHooks (matchers, input, extraArg) {
+  if (!matchers) return
+  for (const matcher of matchers) {
+    for (const hook of matcher.hooks) {
+      hook(input, extraArg)
+    }
+  }
+}
+
+// Mock query() that simulates a realistic agent session:
+// 3 turns, each with 2 tool calls = 22 hook invocations per call.
+// This exercises the full shimmer path: mergeHooks, buildTracerHooks,
+// runStores, and all 9 hook callbacks.
+function mockQuery ({ prompt, options }) {
+  const hooks = options && options.hooks ? options.hooks : {}
+
+  callHooks(hooks.SessionStart, { session_id: 'bench', source: 'api' })
+
+  for (let t = 0; t < 3; t++) {
+    callHooks(hooks.UserPromptSubmit, { session_id: 'bench', prompt: 'p' })
+
+    for (let u = 0; u < 2; u++) {
+      const id = 'tu-' + t + '-' + u
+      callHooks(hooks.PreToolUse, {
+        session_id: 'bench',
+        tool_name: 'Read',
+        tool_input: { path: '/' },
+        tool_use_id: id,
+      }, id)
+      callHooks(hooks.PostToolUse, {
+        session_id: 'bench',
+        tool_response: 'ok',
+        tool_use_id: id,
+      }, id)
+    }
+
+    callHooks(hooks.Stop, { stop_reason: 'end_turn' })
+  }
+
+  callHooks(hooks.SessionEnd, { reason: 'done' })
+
+  return { ok: true }
+}
+
+const wrapped = wrapQuery(mockQuery)
+
+for (let i = 0; i < SESSIONS; i++) {
+  wrapped({ prompt: 'bench', options: { model: 'claude-opus-4-6' } })
+}

benchmark/sirun/plugin-claude-agent-sdk/meta.json

@@ -0,0 +1,17 @@
+{
+  "name": "plugin-claude-agent-sdk",
+  "run": "node index.js",
+  "run_with_affinity": "bash -c \"taskset -c $CPU_AFFINITY node index.js\"",
+  "cachegrind": false,
+  "iterations": 40,
+  "instructions": true,
+  "variants": {
+    "control": {
+      "env": { "USE_TRACER": "0" }
+    },
+    "with-tracer": {
+      "baseline": "control",
+      "env": { "USE_TRACER": "1" }
+    }
+  }
+}

docs/API.md

@@ -28,6 +28,7 @@ tracer.use('pg', {
 <h5 id="ai"></h5>
 <h5 id="amqp10"></h5>
 <h5 id="anthropic"></h5>
+<h5 id="claude-agent-sdk"></h5>
 <h5 id="apollo"></h5>
 <h5 id="avsc"></h5>
 <h5 id="aws-sdk"></h5>
@@ -108,6 +109,7 @@ tracer.use('pg', {
 * [amqp10](./interfaces/export_.plugins.amqp10.html)
 * [amqplib](./interfaces/export_.plugins.amqplib.html)
 * [anthropic](./interfaces/export_.plugins.anthropic.html)
+* [claude-agent-sdk](./interfaces/export_.plugins.claude_agent_sdk.html)
 * [apollo](./interfaces/export_.plugins.apollo.html)
 * [avsc](./interfaces/export_.plugins.avsc.html)
 * [aws-sdk](./interfaces/export_.plugins.aws_sdk.html)

docs/test.ts

@@ -303,6 +303,7 @@ tracer.use('ai', true)
 tracer.use('amqp10');
 tracer.use('amqplib');
 tracer.use('anthropic');
+tracer.use('claude-agent-sdk');
 tracer.use('avsc');
 tracer.use('aws-sdk');
 tracer.use('aws-sdk', awsSdkOptions);

index.d.ts

@@ -227,6 +227,7 @@ interface Plugins {
   "amqp10": tracer.plugins.amqp10;
   "amqplib": tracer.plugins.amqplib;
   "anthropic": tracer.plugins.anthropic;
+  "claude-agent-sdk": tracer.plugins.claude_agent_sdk;
   "apollo": tracer.plugins.apollo;
   "avsc": tracer.plugins.avsc;
   "aws-sdk": tracer.plugins.aws_sdk;
@@ -2232,6 +2233,12 @@ declare namespace tracer {
      */
     interface amqplib extends Instrumentation {}
 
+    /**
+     * This plugin automatically instruments the
+     * [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) module.
+     */
+    interface claude_agent_sdk extends Instrumentation {}
+
     /**
      * This plugin automatically instruments the
      * [anthropic](https://www.npmjs.com/package/@anthropic-ai/sdk) module.