Skip to main content
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
For the full list of required span attributes and what powers the AI dashboard, see the AI Agents feature page.

​
Installation

npm install @monocle.sh/instrumentation-vercel-ai
Peer dependency: ai >= 3.0.0 < 7

​
Usage

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();
provider.addSpanProcessor(new VercelAiSpanProcessor());

// 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. Per-call settings take priority over the global config.

​
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)

AttributeDescription
gen_ai.system_instructionsSystem prompt text
gen_ai.input.messagesInput messages (JSON)
gen_ai.response.textGenerated text
gen_ai.response.tool_callsTool calls made
gen_ai.response.objectGenerated object
gen_ai.tool.inputTool arguments
gen_ai.tool.outputTool result

​
Provider-specific token breakdowns

The processor extracts detailed token metrics from provider metadata when available:
AttributeProviders
gen_ai.usage.input_tokens.cachedOpenAI, Anthropic, Bedrock, DeepSeek
gen_ai.usage.input_tokens.cache_writeAnthropic, Bedrock
gen_ai.usage.input_tokens.cache_missDeepSeek
gen_ai.usage.output_tokens.reasoningOpenAI

​
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).