Skip to content

docs(js): Differentiate manual and automatic AI instrumentation #16843

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
s1gr1d merged 5 commits into from
Mar 12, 2026
Merged

docs(js): Differentiate manual and automatic AI instrumentation #16843

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
61288a8
docs(js): Differentiate manual and automatic AI instrumentation
s1gr1d Mar 9, 2026
2628e2b
change supported/not-supported
s1gr1d Mar 9, 2026
fc9c02e
restructure - add warning for meta-frameworks
s1gr1d Mar 11, 2026
ff1c7ba
fix wrapper names
s1gr1d Mar 11, 2026
571a05e
put alert in platformsection
s1gr1d Mar 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 43 additions & 73 deletions docs/platforms/javascript/common/configuration/integrations/anthropic.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,93 +34,63 @@ supported:
- javascript.gatsby
---

<PlatformSection notSupported={["javascript", "javascript.react", "javascript.angular", "javascript.vue", "javascript.svelte", "javascript.solid", "javascript.ember", "javascript.gatsby"]}>

## Server-Side Usage

<PlatformSection supported={["javascript.nextjs", "javascript.nuxt", "javascript.solidstart", "javascript.sveltekit", "javascript.react-router", "javascript.remix", "javascript.astro", "javascript.tanstackstart-react"]}>

<Alert>

For meta-framework applications using all runtimes, you need to manually wrap your Anthropic client instance with `instrumentAnthropicAiClient`. See instructions in the [Browser-Side Usage](#browser-side-usage) section.

</Alert>

</PlatformSection>

<PlatformSection notSupported={["javascript.nextjs", "javascript.nuxt", "javascript.solidstart", "javascript.sveltekit", "javascript.react-router", "javascript.remix", "javascript.astro", "javascript.tanstackstart-react"]}>

_Import name: `Sentry.anthropicAIIntegration`_

The `anthropicAIIntegration` adds instrumentation for the [`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk) API to capture spans by wrapping Anthropic SDK calls and recording LLM interactions.

<PlatformSection notSupported={["javascript.bun", "javascript.cloudflare"]}>

<Alert>

Enabled by default and automatically captures spans for Anthropic SDK calls. Requires Sentry SDK version `10.28.0` or higher.

</Alert>

<Alert level="warning">
For meta-framework applications running on both client and server, we recommend **setting up the integration manually** using the [`instrumentAnthropicAiClient` wrapper](#manual-instrumentation) to ensure consistent instrumentation across all runtimes.
</Alert>
</PlatformSection>

<PlatformSection supported={["javascript.bun", "javascript.cloudflare"]}>
<PlatformSection supported={["javascript.node", "javascript.aws-lambda", "javascript.azure-functions", "javascript.connect", "javascript.express", "javascript.fastify", "javascript.gcp-functions", "javascript.hapi", "javascript.hono", "javascript.koa", "javascript.nestjs", "javascript.nextjs", "javascript.nuxt", "javascript.solidstart", "javascript.sveltekit", "javascript.react-router", "javascript.remix", "javascript.astro", "javascript.tanstackstart-react", "javascript.electron", "javascript.cordova", "javascript.capacitor", "javascript.deno", "javascript.wasm"]}>

<Alert>
## Automatic Instrumentation

Enabled by default and automatically captures spans for Anthropic SDK calls. Requires Sentry SDK version `10.28.0` or higher.
_Import name: `Sentry.anthropicAIIntegration`_

For other runtimes, like the Browser, the instrumentation needs to be manually enabled. See the [setup instructions below](#browser-side-usage).
<PlatformSection notSupported={["javascript.node", "javascript.connect", "javascript.hapi", "javascript.koa"]}>
<Alert>
If you are using a different runtime (like Bun, Cloudflare Workers or a Browser) or experiencing missing spans, you need to use **[Manual Instrumentation](#manual-instrumentation)** to explicitly wrap your AI client instance instead.
</Alert>
</PlatformSection>

</Alert>
The `anthropicAIIntegration` adds instrumentation for the [`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk) API to capture spans by wrapping Anthropic SDK calls and recording LLM interactions.

</PlatformSection>

To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section.
In Node.js runtimes, this integration is enabled by default and automatically captures spans for Anthropic SDK calls (requires Sentry SDK version `10.28.0` or higher).

</PlatformSection>
To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section.

</PlatformSection>

<PlatformSection supported={["javascript", "javascript.react", "javascript.angular", "javascript.vue", "javascript.svelte", "javascript.solid", "javascript.ember", "javascript.gatsby", "javascript.nextjs", "javascript.nuxt", "javascript.solidstart", "javascript.sveltekit", "javascript.react-router", "javascript.remix", "javascript.astro", "javascript.tanstackstart-react", "javascript.electron", "javascript.cloudflare"]}>
<PlatformSection notSupported={["javascript.node", "javascript.connect", "javascript.hapi", "javascript.koa"]}>

## Browser-Side Usage
## Manual Instrumentation

_Import name: `Sentry.instrumentAnthropicAiClient`_
_Import name: `Sentry.instrumentAnthropicAiClient`_

<PlatformSection supported={["javascript.cloudflare"]}>
The `instrumentAnthropicAiClient` helper adds instrumentation for the [`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk) API to capture spans by wrapping Anthropic SDK calls and recording LLM interactions with configurable input/output recording. You need to manually wrap your Anthropic client instance with this helper.

<Alert>
See the example below:

For Cloudflare Workers, manual instrumentation is required using `instrumentAnthropicAiClient`.
```javascript
import Anthropic from "@anthropic-ai/sdk";

</Alert>

</PlatformSection>

The `instrumentAnthropicAiClient` helper adds instrumentation for the [`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk) API to capture spans by wrapping Anthropic SDK calls and recording LLM interactions with configurable input/output recording. You need to manually wrap your Anthropic client instance with this helper. See example below:

```javascript
import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({
const anthropic = new Anthropic({
apiKey: "your-api-key", // Warning: API key will be exposed in browser!
});

const client = Sentry.instrumentAnthropicAiClient(anthropic, {
const client = Sentry.instrumentAnthropicAiClient(anthropic, {
recordInputs: true,
recordOutputs: true,
});

// Use the wrapped client instead of the original anthropic instance
const response = await client.messages.create({
// Use the wrapped client instead of the original anthropic instance
const response = await client.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }],
});
```
```

To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section.
To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section.

</PlatformSection>

Expand Down Expand Up @@ -148,34 +118,34 @@ Defaults to `true` if `sendDefaultPii` is `true`.

**Usage**

<PlatformSection notSupported={["javascript", "javascript.react", "javascript.angular", "javascript.vue", "javascript.svelte", "javascript.solid", "javascript.ember", "javascript.gatsby"]}>
<PlatformSection supported={["javascript.node", "javascript.aws-lambda", "javascript.azure-functions", "javascript.connect", "javascript.express", "javascript.fastify", "javascript.gcp-functions", "javascript.hapi", "javascript.hono", "javascript.koa", "javascript.nestjs", "javascript.nextjs", "javascript.nuxt", "javascript.solidstart", "javascript.sveltekit", "javascript.react-router", "javascript.remix", "javascript.astro", "javascript.tanstackstart-react", "javascript.electron", "javascript.cordova", "javascript.capacitor", "javascript.deno", "javascript.wasm"]}>

Using the `anthropicAIIntegration` integration:
Using the `anthropicAIIntegration` integration for **automatic instrumentation**:

```javascript
Sentry.init({
```javascript
Sentry.init({
dsn: "____PUBLIC_DSN____",
// Tracing must be enabled for agent monitoring to work
tracesSampleRate: 1.0,
// Tracing must be enabled for agent monitoring to work
tracesSampleRate: 1.0,
integrations: [
Sentry.anthropicAIIntegration({
// your options here
}),
Sentry.anthropicAIIntegration({
// your options here
}),
],
});
```
```

</PlatformSection>

<PlatformSection supported={["javascript", "javascript.react", "javascript.angular", "javascript.vue", "javascript.svelte", "javascript.solid", "javascript.ember", "javascript.gatsby", "javascript.nextjs", "javascript.nuxt", "javascript.solidstart", "javascript.sveltekit", "javascript.react-router", "javascript.remix", "javascript.astro", "javascript.tanstackstart-react", "javascript.electron", "javascript.cloudflare"]}>
<PlatformSection notSupported={["javascript.node", "javascript.connect", "javascript.hapi", "javascript.koa"]}>

Using the `instrumentAnthropicAiClient` helper:
Using the `instrumentAnthropicAiClient` wrapper for **manual instrumentation**:

```javascript
const client = Sentry.instrumentAnthropicAiClient(anthropic, {
```javascript
const client = Sentry.instrumentAnthropicAiClient(anthropic, {
// your options here
});
```
```

</PlatformSection>

Expand All @@ -195,4 +165,4 @@ Streaming and non-streaming requests are automatically detected and handled appr

## Supported Versions

- `@anthropic-ai/sdk`: `>=0.19.2 <1.0.0`
- `@anthropic-ai/sdk`: `>=0.19.2 <1.0.0`
92 changes: 36 additions & 56 deletions docs/platforms/javascript/common/configuration/integrations/google-genai.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,79 +34,59 @@ supported:
- javascript.gatsby
---

<PlatformSection notSupported={["javascript", "javascript.react", "javascript.angular", "javascript.vue", "javascript.svelte", "javascript.solid", "javascript.ember", "javascript.gatsby"]}>

## Server-Side Usage

<PlatformSection supported={["javascript.nextjs", "javascript.nuxt", "javascript.solidstart", "javascript.sveltekit", "javascript.react-router", "javascript.remix", "javascript.astro", "javascript.tanstackstart-react"]}>

<Alert>

For meta-framework applications using all runtimes, you need to manually wrap your Google Gen AI client instance with `instrumentGoogleGenAIClient`. See instructions in the [Browser-Side Usage](#browser-side-usage) section.

</Alert>

</PlatformSection>

<PlatformSection notSupported={["javascript.nextjs", "javascript.nuxt", "javascript.solidstart", "javascript.sveltekit", "javascript.react-router", "javascript.remix", "javascript.astro", "javascript.tanstackstart-react"]}>

_Import name: `Sentry.googleGenAIIntegration`_

The `googleGenAIIntegration` adds instrumentation for the [`@google/genai`](https://www.npmjs.com/package/@google/genai) SDK to capture spans by wrapping Google Gen AI SDK calls and recording LLM interactions.

<PlatformSection notSupported={["javascript.bun", "javascript.cloudflare"]}>

<Alert>

Enabled by default and automatically captures spans for Google Gen AI SDK calls. Requires Sentry SDK version `10.28.0` or higher.

</Alert>

<Alert level="warning">
For meta-framework applications running on both client and server, we recommend **setting up the integration manually** using the [`instrumentGoogleGenAIClient` wrapper](#manual-instrumentation) to ensure consistent instrumentation across all runtimes.
</Alert>
Comment thread
s1gr1d marked this conversation as resolved.
</PlatformSection>

<PlatformSection supported={["javascript.bun", "javascript.cloudflare"]}>
<PlatformSection supported={["javascript.node", "javascript.aws-lambda", "javascript.azure-functions", "javascript.connect", "javascript.express", "javascript.fastify", "javascript.gcp-functions", "javascript.hapi", "javascript.hono", "javascript.koa", "javascript.nestjs", "javascript.nextjs", "javascript.nuxt", "javascript.solidstart", "javascript.sveltekit", "javascript.react-router", "javascript.remix", "javascript.astro", "javascript.tanstackstart-react", "javascript.electron", "javascript.cordova", "javascript.capacitor", "javascript.deno", "javascript.wasm"]}>

<Alert>
## Automatic Instrumentation

Enabled by default and automatically captures spans for Google Gen AI SDK calls. Requires Sentry SDK version `10.28.0` or higher.
_Import name: `Sentry.googleGenAIIntegration`_

For other runtimes, like the Browser, the instrumentation needs to be manually enabled. See the [setup instructions below](#browser-side-usage).
<PlatformSection notSupported={["javascript.node", "javascript.connect", "javascript.hapi", "javascript.koa"]}>
<Alert>
If you are using a different runtime (like Bun, Cloudflare Workers or a Browser) or experiencing missing spans, you need to use **[Manual Instrumentation](#manual-instrumentation)** to explicitly wrap your AI client instance instead.
</Alert>
</PlatformSection>

</Alert>
The `googleGenAIIntegration` adds instrumentation for the [`@google/genai`](https://www.npmjs.com/package/@google/genai) SDK to capture spans by wrapping Google Gen AI SDK calls and recording LLM interactions.

</PlatformSection>
In Node.js runtimes, this integration is enabled by default and automatically captures spans for Google Gen AI SDK calls (requires Sentry SDK version `10.28.0` or higher).

To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section.
To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section.

</PlatformSection>

</PlatformSection>
<PlatformSection notSupported={["javascript.node", "javascript.connect", "javascript.hapi", "javascript.koa"]}>

<PlatformSection supported={["javascript", "javascript.react", "javascript.angular", "javascript.vue", "javascript.svelte", "javascript.solid", "javascript.ember", "javascript.gatsby", "javascript.nextjs", "javascript.nuxt", "javascript.solidstart", "javascript.sveltekit", "javascript.react-router", "javascript.remix", "javascript.astro", "javascript.tanstackstart-react", "javascript.electron", "javascript.cloudflare"]}>
## Manual Instrumentation

## Browser-Side Usage
_Import name: `Sentry.instrumentGoogleGenAIClient`_

_Import name: `Sentry.instrumentGoogleGenAIClient`_
The `instrumentGoogleGenAIClient` helper adds instrumentation for the [`@google/genai`](https://www.npmjs.com/package/@google/genai) SDK to capture spans by wrapping Google Gen AI SDK calls and recording LLM interactions with configurable input/output recording. You need to manually wrap your Google Gen AI client instance with this helper.

The `instrumentGoogleGenAIClient` helper adds instrumentation for the [`@google/genai`](https://www.npmjs.com/package/@google/genai) SDK to capture spans by wrapping Google Gen AI SDK calls and recording LLM interactions with configurable input/output recording. You need to manually wrap your Google Gen AI client instance with this helper. See example below:
See example below:

```javascript
import { GoogleGenAI } from "@google/genai";
```javascript
import { GoogleGenAI } from "@google/genai";

const genAI = new GoogleGenAI({
apiKey: "your-api-key", // Warning: API key will be exposed in browser!
});
const genAI = new GoogleGenAI({
apiKey: "your-api-key", // Warning: API key will be exposed in browser!
});

const client = Sentry.instrumentGoogleGenAIClient(genAI, {
recordInputs: true,
recordOutputs: true,
});
const client = Sentry.instrumentGoogleGenAIClient(genAI, {
recordInputs: true,
recordOutputs: true,
});

// Use the wrapped client instead of the original genAI instance
const result = await client.models.generateContent("Hello!");
```
// Use the wrapped client instead of the original genAI instance
const result = await client.models.generateContent("Hello!");
```

To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section.
To customize what data is captured (such as inputs and outputs), see the [Options](#options) in the Configuration section.

</PlatformSection>

Expand Down Expand Up @@ -134,9 +114,9 @@ Defaults to `true` if `sendDefaultPii` is `true`.

**Usage**

<PlatformSection notSupported={["javascript", "javascript.react", "javascript.angular", "javascript.vue", "javascript.svelte", "javascript.solid", "javascript.ember", "javascript.gatsby"]}>
<PlatformSection supported={["javascript.node", "javascript.aws-lambda", "javascript.azure-functions", "javascript.connect", "javascript.express", "javascript.fastify", "javascript.gcp-functions", "javascript.hapi", "javascript.hono", "javascript.koa", "javascript.nestjs", "javascript.nextjs", "javascript.nuxt", "javascript.solidstart", "javascript.sveltekit", "javascript.react-router", "javascript.remix", "javascript.astro", "javascript.tanstackstart-react", "javascript.electron", "javascript.cordova", "javascript.capacitor", "javascript.deno", "javascript.wasm"]}>

Using the `googleGenAIIntegration` integration:
Using the `googleGenAIIntegration` integration for **automatic instrumentation**:

```javascript
Sentry.init({
Expand All @@ -153,9 +133,9 @@ Sentry.init({

</PlatformSection>

<PlatformSection supported={["javascript", "javascript.react", "javascript.angular", "javascript.vue", "javascript.svelte", "javascript.solid", "javascript.ember", "javascript.gatsby", "javascript.nextjs", "javascript.nuxt", "javascript.solidstart", "javascript.sveltekit", "javascript.react-router", "javascript.remix", "javascript.astro", "javascript.tanstackstart-react", "javascript.electron", "javascript.cloudflare"]}>
<PlatformSection notSupported={["javascript.node", "javascript.connect", "javascript.hapi", "javascript.koa"]}>

Using the `instrumentGoogleGenAIClient` helper:
Using the `instrumentGoogleGenAIClient` wrapper for **manual instrumentation**:

```javascript
const client = Sentry.instrumentGoogleGenAIClient(genAI, {
Expand Down
Loading
Loading