Sentry Nextjs Sdk

# AI Monitoring — Sentry Next.js SDK

> OpenAI integration: `@sentry/nextjs` ≥10.53.0+  
> Vercel AI SDK integration: ≥10.53.0+  
> Anthropic integration: ≥10.53.0+

> ⚠️ **Tracing must be enabled.** AI monitoring piggybacks on tracing infrastructure. `tracesSampleRate` must be > 0.

---

## Overview

Sentry AI Agents Monitoring automatically tracks:
- Agent runs and error rates
- LLM calls (model, token counts, estimated cost)
- Tool calls and outputs
- Agent handoffs
- Full prompt/completion data (opt-in)
- Performance bottlenecks across the AI pipeline

---

## Supported AI Libraries

| Library | Integration API | Auto-enabled (Node server)? | Min SDK Version |
|---------|----------------|----------------------------|----------------|
| **OpenAI** (`openai`) | `openAIIntegration` / `instrumentOpenAiClient` | ✅ Yes | **10.53.0** |
| **Vercel AI SDK** (`ai`) | `vercelAIIntegration` | ✅ Yes (Node), ❌ Edge manual | **10.53.0** |
| **Anthropic** (`@anthropic-ai/sdk`) | `anthropicAIIntegration` / `instrumentAnthropicAiClient` | ✅ Yes | **10.53.0** |

---

## OpenAI Integration

### Which API to Use?

| Context | API |
|---------|-----|
| **Next.js server-side** (API routes, Server Components, Route Handlers) | `Sentry.openAIIntegration()` in `sentry.server.config.ts` |
| **Browser / client-side** | `Sentry.instrumentOpenAiClient(openaiInstance)` — manual wrapper |

### Server-Side Setup (`sentry.server.config.ts`)

`openAIIntegration` is **enabled by default** on the server. Pass it explicitly to customize options:

```typescript
// sentry.server.config.ts
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.SENTRY_DSN,

  // Tracing MUST be enabled for AI monitoring
  tracesSampleRate: 1.0,
  streamGenAiSpans: true,
  sendDefaultPii: true,

  integrations: [
    Sentry.openAIIntegration(), // recordInputs/recordOutputs default to true with sendDefaultPii
  ],
});
```

### Client-Side / Manual Wrapping

Prompt/output capture assumes the matching client-side `Sentry.init()` also sets `sendDefaultPii: true`.

```typescript
import OpenAI from "openai";
import * as Sentry from "@sentry/nextjs";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY, // ⚠️ Never expose this in the browser!
});

// Wrap once at module level — reuse this client everywhere.
// Input/output recording follows sendDefaultPii unless explicitly overridden.
const client = Sentry.instrumentOpenAiClient(openai);

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});
```

### Streaming — Important

For streamed responses, you **must** pass `stream_options: { include_usage: true }`. Without this, OpenAI does not include token counts in streamed responses, so Sentry cannot capture usage metrics:

```typescript
const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
  stream_options: { include_usage: true }, // ← REQUIRED for token tracking
});
```

### OpenAI Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `recordInputs` | `boolean` | `true` if `sendDefaultPii: true` | Capture prompts/messages sent to OpenAI |
| `recordOutputs` | `boolean` | `true` if `sendDefaultPii: true` | Capture generated text/responses |

**Supported versions:** `openai` ≥4.0.0 <7

---

## Vercel AI SDK Integration

### Setup

The integration is **auto-enabled** in the Node runtime. For the Edge runtime, add it explicitly:

```typescript
// sentry.server.config.ts — Node runtime (auto-enabled, customize here)
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  streamGenAiSpans: true,
  sendDefaultPii: true,
  integrations: [
    Sentry.vercelAIIntegration({
      force: true, // ← Required for Vercel production deployments (see note below)
    }),
  ],
});
```

```typescript
// se