Vercel AI SDK

This guide covers how to instrument the Vercel AI SDK for monitoring LLM calls, token usage, and costs. You will learn how to:

Install and configure the instrumentation
Track AI operations (generateText, streamText, etc.)
Group calls into conversations

Overview

For the full list of required span attributes and what powers the AI dashboard, see the AI Agents feature page.

Installation

Terminal

npm install @monocle.sh/instrumentation-vercel-ai

Peer dependency: ai >= 3.0.0 < 7

With the AdonisJS agent

Registration through integrations requires AdonisJS agent 2.x. See the migration guide when upgrading from 1.x.

Install this integration separately and add vercelAi() to config/monocle.ts. Installing the package alone does not activate it.

config/monocle.ts

import { defineConfig } from "@monocle.sh/adonisjs-agent";
import { vercelAi } from "@monocle.sh/instrumentation-vercel-ai/integration";
import env from "#start/env";

export default defineConfig({
  apiKey: env.get("MONOCLE_API_KEY"),
  integrations: [vercelAi({ recordInputs: false, recordOutputs: false })],
});

The agent enables the import hooks and adds the span processor before starting its telemetry SDK. Keep the otel.ts import first in your application entry points. Omit vercelAi() to disable this integration.

Without the AdonisJS agent

The instrumentation has two parts: the VercelAiInstrumentation that hooks into the AI SDK to enable telemetry, and the VercelAiSpanProcessor that normalizes span attributes to OpenTelemetry GenAI Semantic Conventions.

instrumentation.ts

import { VercelAiInstrumentation, VercelAiSpanProcessor } from "@monocle.sh/instrumentation-vercel-ai";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";

// Add the span processor to your tracer provider
const provider = new NodeTracerProvider({
  spanProcessors: [new VercelAiSpanProcessor()],
});
provider.register();

// Enable auto-instrumentation
const instrumentation = new VercelAiInstrumentation();
instrumentation.enable();

Once enabled, all generateText, streamText, generateObject, streamObject, embed, embedMany, and rerank calls are automatically instrumented.

example.ts

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

// This automatically creates spans with token usage, model info, etc.
const result = await generateText({
  model: openai("gpt-4o"),
  prompt: "What is observability?",
});

Configuration

const instrumentation = new VercelAiInstrumentation({
  // Record prompt/input data in spans (default: true)
  recordInputs: true,

  // Record response/output data in spans (default: true)
  recordOutputs: true,
});

You can also control recording per call via the AI SDK’s experimental_telemetry option. Explicit recordInputs and recordOutputs options on the integration take priority. When an option is omitted, it falls back to the per-call setting, then to true. A per-call experimental_telemetry.isEnabled: false still disables telemetry for that call.

Conversation tracking

Use withConversationId() to group multiple AI calls into a single conversation. This sets gen_ai.conversation.id on all spans created within the callback, enabling the Conversations tab in the Monocle AI dashboard.

chat.ts

import { withConversationId, getConversationId } from "@monocle.sh/instrumentation-vercel-ai";

await withConversationId("conv-abc-123", async () => {
  // All AI calls here share the same conversation ID
  const response = await generateText({
    model: openai("gpt-4o"),
    prompt: userMessage,
  });

  // You can also read the current conversation ID
  const currentId = getConversationId(); // "conv-abc-123"
});

Spans

The instrumentation does not create spans directly. It enables the Vercel AI SDK’s built-in telemetry and processes those spans through the VercelAiSpanProcessor to normalize attributes.

Pipeline spans

A span is created for each top-level AI call (generateText, streamText, etc.). The span name is normalized to {operation} {functionId} (e.g., invoke_agent weather-app).

Inner LLM call spans

A child span is created for the actual LLM API call. The span name is {operation} {modelId} (e.g., generate_text gpt-4o).

Tool call spans

Each tool invocation creates a span named execute_tool {toolName}. The instrumentation also detects Vercel AI SDK v5 tool errors embedded in result content and records them as exceptions on the corresponding span.

Vercel AI-specific attributes

In addition to the standard AI attributes, the Vercel AI instrumentation emits these extra attributes.

Input/output attributes (when recording is enabled)

Attribute	Description
`gen_ai.system_instructions`	System prompt text
`gen_ai.input.messages`	Input messages (JSON)
`gen_ai.response.text`	Generated text
`gen_ai.response.tool_calls`	Tool calls made
`gen_ai.response.object`	Generated object
`gen_ai.tool.input`	Tool arguments
`gen_ai.tool.output`	Tool result

Provider-specific token breakdowns

The processor extracts detailed token metrics from provider metadata when available:

Attribute	Providers
`gen_ai.usage.input_tokens.cached`	OpenAI, Anthropic, Bedrock, DeepSeek
`gen_ai.usage.input_tokens.cache_write`	Anthropic, Bedrock
`gen_ai.usage.input_tokens.cache_miss`	DeepSeek
`gen_ai.usage.output_tokens.reasoning`	OpenAI

Vercel AI SDK native attributes

Remaining Vercel-native attributes are preserved under the vercel.ai.* namespace (e.g., vercel.ai.response.msToFirstChunk, vercel.ai.response.avgOutputTokensPerSecond).

Getting Started

Monocle Studio

Frameworks

Features

Integrations

Migrations

Other

Overview

Installation

With the AdonisJS agent

Without the AdonisJS agent

Configuration

Conversation tracking

Spans

Pipeline spans

Inner LLM call spans

Tool call spans

Vercel AI-specific attributes

Input/output attributes (when recording is enabled)

Provider-specific token breakdowns

Vercel AI SDK native attributes

​Overview

​Installation

​With the AdonisJS agent

​Without the AdonisJS agent

​Configuration

​Conversation tracking

​Spans

​Pipeline spans

​Inner LLM call spans

​Tool call spans

​Vercel AI-specific attributes

​Input/output attributes (when recording is enabled)

​Provider-specific token breakdowns

​Vercel AI SDK native attributes

Overview

Installation

With the AdonisJS agent

Without the AdonisJS agent

Configuration

Conversation tracking

Spans

Pipeline spans

Inner LLM call spans

Tool call spans

Vercel AI-specific attributes

Input/output attributes (when recording is enabled)

Provider-specific token breakdowns

Vercel AI SDK native attributes