Vercel AI SDK

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

With the AdonisJS agent

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

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

export default defineConfig({
  dsn: env.get('MONOCLE_DSN'),
  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.

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.

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.

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)

Provider-specific token breakdowns

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

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