---
title: "OpenAI"
description: "Adds instrumentation for the OpenAI SDK."
url: https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai/
---

# OpenAI | Sentry for Next.js

For meta-framework applications running on both client and server, we recommend using the [`instrumentOpenAiClient` wrapper](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#instrument-the-client) to ensure consistent instrumentation across all runtimes.

## [Automatic Instrumentation](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#automatic-instrumentation)

*Import name: `Sentry.openAIIntegration`*

If you are using a different runtime (like Bun, Cloudflare Workers or a Browser) or experiencing missing spans, **[wrap the client](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#instrument-the-client)** with `instrumentOpenAiClient` instead.

The `openAIIntegration` adds instrumentation for the [`openai`](https://www.npmjs.com/package/openai) SDK to capture spans by wrapping OpenAI SDK calls and recording LLM interactions.

In Node.js runtimes, this integration is enabled by default and automatically captures spans for OpenAI 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](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#options) in the Configuration section.

## [Instrument the Client](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#instrument-the-client)

*Import name: `Sentry.instrumentOpenAiClient`*

The `instrumentOpenAiClient` helper instruments the [`openai`](https://www.npmjs.com/package/openai) SDK by wrapping your client instance and recording LLM interactions with configurable input/output capture.

See example below:

```javascript
import OpenAI from "openai";

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

const client = Sentry.instrumentOpenAiClient(openai, {
  recordInputs: true,
  recordOutputs: true,
});

// Use the wrapped client instead of the original openai instance
const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});
```

To customize what data is captured (such as inputs and outputs), see the [Options](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#options) in the Configuration section.

## [Configuration](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#configuration)

### [Options](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#options)

The following options control what data is captured from OpenAI SDK calls:

#### [`recordInputs`](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#recordinputs)

*Type: `boolean` (optional)*

Records inputs to OpenAI SDK calls (such as prompts and messages).

Defaults to `true` if `dataCollection.genAI.inputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`.

#### [`recordOutputs`](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#recordoutputs)

*Type: `boolean` (optional)*

Records outputs from OpenAI SDK calls (such as generated text and responses).

Defaults to `true` if `dataCollection.genAI.outputs` is `true` (which is the default when using `dataCollection`), or if the deprecated `sendDefaultPii` is `true`.

**Usage**

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

```javascript
Sentry.init({
  dsn: "_https://<key>@o<orgId>.ingest.sentry.io/<projectId>_",
  // Tracing must be enabled for agent tracing to work
  tracesSampleRate: 1.0,
  integrations: [
    Sentry.openAIIntegration({
      // your options here
    }),
  ],
});
```

Using the `instrumentOpenAiClient` wrapper:

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

## [Supported Operations](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#supported-operations)

By default, tracing support is added to the following OpenAI SDK calls:

* `chat.completions.create()` - Chat completion requests
* `responses.create()` - Response SDK requests

Streaming and non-streaming requests are automatically detected and handled appropriately.

Both APIs produce the same span type in Sentry: op `gen_ai.chat`, name like `chat <model>`. There is no separate `gen_ai.responses` span — `responses.create()` is still a model chat request under the hood, so it uses the standard chat operation.

Instrumented calls record model, token usage, latency, and (when enabled) inputs/outputs on the LLM span. If you pass `tools` to the request, Sentry stores the tool definitions on the span and records any tool calls the model returns as span attributes.

### [Tool execution spans](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#tool-execution-spans)

The OpenAI SDK does **not** run your tools — your application does, after the model returns `tool_calls`. Because of that, `instrumentOpenAiClient` / `openAIIntegration` do **not** create `gen_ai.execute_tool` spans for local tool handlers.

To get the full agent tree (`gen_ai.invoke_agent` → `gen_ai.chat` + `gen_ai.execute_tool`), wrap your tool loop with [manual instrumentation](https://docs.sentry.io/platforms/javascript/guides/nextjs/agent-tracing/manual-instrumentation.md).

### [Streaming token usage](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#streaming-token-usage)

When using OpenAI's streaming API, you must also pass `stream_options: { include_usage: true }` to receive token usage data. Without this option, OpenAI does not include `prompt_tokens` or `completion_tokens` in streamed responses, and Sentry will be unable to capture `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` on the resulting span. This is an OpenAI API behavior, not a Sentry limitation. See [OpenAI API reference](https://platform.openai.com/docs/api-reference/chat/create).

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

## [Supported Versions](https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/integrations/openai.md#supported-versions)

* `openai`: `>=4.0.0 <7`