Skip to content

vercelai.mdx

Latest commit

 

History

History
269 lines (198 loc) · 7.68 KB

vercelai.mdx

File metadata and controls

269 lines (198 loc) · 7.68 KB
title Vercel AI
description Adds instrumentation for Vercel AI SDK.
supported
javascript.node
javascript.aws-lambda
javascript.azure-functions
javascript.connect
javascript.deno
javascript.express
javascript.fastify
javascript.gcp-functions
javascript.cloudflare
javascript.hapi
javascript.hono
javascript.koa
javascript.nestjs
javascript.electron
javascript.nextjs
javascript.nuxt
javascript.solidstart
javascript.sveltekit
javascript.react-router
javascript.remix
javascript.astro
javascript.bun
javascript.tanstackstart-react

Requires SDK version 10.6.0 or higher for Node.js, Cloudflare Workers, Vercel Edge Functions and Bun. Requires SDK version 10.12.0 or higher for Deno.

Import name: Sentry.vercelAIIntegration

The vercelAIIntegration adds instrumentation for the ai SDK by Vercel to capture spans using the AI SDK's built-in Telemetry.

<PlatformSection notSupported={["javascript.cloudflare", "javascript.nextjs"]}> It is enabled by default and will automatically capture spans for all ai function calls. You can opt-in to capture inputs and outputs by setting recordInputs and recordOutputs in the integration config:

Sentry.init({
  dsn: "____PUBLIC_DSN____"
  tracesSampleRate: 1.0,
  integrations: [
    Sentry.vercelAIIntegration({
      recordInputs: true,
      recordOutputs: true,
    }),
  ],
});

<PlatformSection supported={['javascript.cloudflare']}> This integration is not enabled by default. You need to manually enable it by passing Sentry.vercelAIIntegration() to Sentry.init:

Sentry.init({
  dsn: "____PUBLIC_DSN____"
  tracesSampleRate: 1.0,
  integrations: [Sentry.vercelAIIntegration()],
});

<PlatformSection supported={['javascript.nextjs']}> This integration is enabled by default in the Node runtime, but not in the Edge runtime. You need to manually enable it by passing Sentry.vercelAIIntegration() to Sentry.init in your sentry.edge.config.js file:

Sentry.init({
  dsn: "____PUBLIC_DSN____"
  tracesSampleRate: 1.0,
  integrations: [Sentry.vercelAIIntegration()],
});

<PlatformSection supported={['javascript.cloudflare', 'javascript.nextjs']}> To correctly capture spans, pass the experimental_telemetry object with isEnabled: true to every generateText, generateObject, streamText, and ToolLoopAgent call. For more details, see the AI SDK Telemetry Metadata docs.

const result = await generateText({
  model: openai("gpt-4o"),
  experimental_telemetry: {
    isEnabled: true,
    recordInputs: true,
    recordOutputs: true,
  },
});

<PlatformSection notSupported={['javascript.cloudflare']}>

Options

force

Requires SDK version 9.29.0 or higher.

Type: boolean

Forces the integration to be active, even when the ai module is not detected or available. This is useful when you want to ensure the integration is always enabled regardless of module detection.

Defaults to false.

Sentry.init({
  integrations: [Sentry.vercelAIIntegration({ force: true })],
});

<PlatformSection supported={["javascript.nextjs"]}> This option is not available in the Edge runtime. There, the integration is forced when it is enabled.

<PlatformSection notSupported={['javascript.nextjs']}>

recordInputs

Requires SDK version 9.27.0 or higher.

Type: boolean

Records inputs to the ai function call.

Defaults to true if sendDefaultPii is true or if you explicitly set experimental_telemetry.isEnabled to true in your ai function callsites.

Sentry.init({
  integrations: [Sentry.vercelAIIntegration({ recordInputs: true })],
});

recordOutputs

Requires SDK version 9.27.0 or higher.

Type: boolean

Records outputs to the ai function call.

Defaults to true if sendDefaultPii is true or if you explicitly set experimental_telemetry.isEnabled to true in your ai function callsites.

Sentry.init({
  integrations: [Sentry.vercelAIIntegration({ recordOutputs: true })],
});

ToolLoopAgent

The integration also captures spans for the ToolLoopAgent class. Each call to generate() or stream() creates an agent span with individual LLM requests and tool executions as child spans.

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

No additional configuration is needed — ToolLoopAgent spans are captured automatically.

<PlatformSection supported={['javascript.cloudflare', 'javascript.nextjs']}>

Pass experimental_telemetry with isEnabled: true to the ToolLoopAgent constructor to correctly capture spans:

const agent = new ToolLoopAgent({
  model: openai("gpt-4o"),
  tools: { /* ... */ },
  experimental_telemetry: { isEnabled: true },
});

const result = await agent.generate({
  prompt: "What is the weather in San Francisco?",
});

Identifying functions

In order to make it easier to correlate captured spans with the function calls we recommend setting functionId in experimental_telemetry in all generation function calls:

const result = await generateText({
  model: openai("gpt-4o"),
  experimental_telemetry: {
    isEnabled: true,
    functionId: "my-awesome-function",
  },
});

For ToolLoopAgent, set functionId in the constructor:

const agent = new ToolLoopAgent({
  model: openai("gpt-4o"),
  tools: { /* ... */ },
  experimental_telemetry: {
    isEnabled: true,
    functionId: "weather-agent",
  },
});

Configuration

By default this integration adds tracing support to all ai function callsites. If you need to disable span collection for a specific call, you can do so by setting experimental_telemetry.isEnabled to false in the first argument of the function call.

const result = await generateText({
  model: openai("gpt-4o"),
  experimental_telemetry: { isEnabled: false },
});

If you set experimental_telemetry.recordInputs and experimental_telemetry.recordOutputs it will override the default behavior of collecting inputs and outputs for that function call.

const result = await generateText({
  model: openai("gpt-4o"),
  experimental_telemetry: {
    isEnabled: true,
    recordInputs: true,
    recordOutputs: true,
  },
});

Supported Versions

  • ai: >=3.0.0 <=6

Troubleshooting

<PlatformSection supported={['javascript.nextjs']}>

When deploying to Vercel, you may notice that AI SDK spans have raw names like ai.toolCall or ai.streamText instead of the expected semantic names like gen_ai.execute_tool or gen_ai.stream_text.

This happens because the ai package is bundled (not externalized) in Next.js production builds, which prevents the integration from automatically detecting and instrumenting the module.

To fix this, explicitly enable the integration with force: true in your sentry.server.config.ts:

Sentry.init({
  dsn: "____PUBLIC_DSN____",
  integrations: [Sentry.vercelAIIntegration({ force: true })],
});

The force option ensures the integration registers its span processors regardless of module detection.