Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.monocle.sh/llms.txt

Use this file to discover all available pages before exploring further.

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