Skip to Content
Launching the open-source gateway

Vercel AI SDK (tracing)

The AI SDK  (by Vercel) is a TypeScript toolkit for building AI-powered applications with Next.js, React, and other frameworks. It provides unified APIs for text generation, streaming, tool use, and structured outputs across multiple LLM providers. Respan captures model calls, tool execution, and token usage for every step of a run when AI SDK telemetry is enabled.

Set up Respan

Create an account at platform.respan.ai  and grab an API key .

Paste this into your coding agent:

Help me set up Respan tracing with the Vercel AI SDK integration.
Follow https://www.respan.ai/docs/integrations/vercel-ai-sdk.md

Setup

Supported AI SDK range: ai >=4 <8 (AI SDK 4.x through 7.x). AI SDK 7.x requires @respan/instrumentation-vercel 1.0.10 or later for modern gen_ai.* span support and AI SDK telemetry auto-registration, plus the optional peer package @ai-sdk/otel. AI SDK 4.x-6.x use the legacy experimental_telemetry option and do not require @ai-sdk/otel.

Install packages

Terminal
npm install ai@^7 @ai-sdk/otel @ai-sdk/openai @respan/respan @respan/instrumentation-vercel@^1.0.10

Set environment variables

Terminal
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

OPENAI_API_KEY is used for LLM requests. RESPAN_API_KEY is used to export traces to Respan.

Initialize Respan

Create instrumentation.ts in your project root (same level as package.json). Next.js calls register() automatically at startup.

instrumentation.ts
import { Respan } from "@respan/respan";
import { VercelAIInstrumentor } from "@respan/instrumentation-vercel";

export async function register() {
  const respan = new Respan({
    apiKey: process.env.RESPAN_API_KEY,
    instrumentations: [new VercelAIInstrumentor()],
  });
  await respan.initialize();
}

Then add serverExternalPackages to next.config.ts:

next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  serverExternalPackages: [
    "@respan/respan",
    "@respan/instrumentation-vercel",
    "ai",
    "@ai-sdk/otel",
  ],
};

export default nextConfig;

VercelAIInstrumentor automatically registers the AI SDK 7 OpenTelemetry bridge when @ai-sdk/otel is installed. If the optional peer is missing, initialization logs a warning and AI SDK 7 calls do not emit the required spans.

Initialize and run

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

const result = await generateText({
  model: openai("gpt-4.1-nano"),
  prompt: "Tell me a joke about AI",
  telemetry: { isEnabled: true },
});

console.log(result.text);

View your trace

Open the Traces page  to see your AI calls with input/output, token usage, and tool calls.

Each generateText or streamText call is one trace. The AI SDK reports the whole tree, so you don’t wrap your calls in anything. A call that uses one tool looks like this:

agent.invoke_agent_gpt-4.1-nano
├─ task (step 1)
│  ├─ llm.gpt-4.1-nano       asks for the tool
│  └─ tool.getWeather
└─ task (step 2)
   └─ llm.gpt-4.1-nano       writes the answer

Speech and transcription

Requires ai 7.0.124 or later, @ai-sdk/otel 1.0.124 or later, and @respan/instrumentation-vercel 1.3.1 or later.

generateSpeech creates a speech span, and transcribe and experimental_streamTranscribe create transcribe spans. Respan records the speech text, the transcript, and the audio size and format. Audio bytes aren’t recorded.

Provider usage stays in span metadata in the provider’s own units, such as audio seconds or input characters. To stop recording the text, set telemetry.recordInputs or telemetry.recordOutputs to false.

Configuration

ParameterTypeDefaultDescription
apiKeystring | undefinedRESPAN_API_KEY env varRespan API key.
baseURLstring | undefined"https://api.respan.ai"API base URL.
instrumentationsRespanInstrumentation[][]Plugin instrumentations to activate.

Attributes

With app-managed AI SDK 7 OpenTelemetry attributes

For global custom attributes, register a configured bridge before Respan initializes and disable the instrumentor’s automatic registration. Register the bridge only once during application startup.

TypeScript
import { OpenTelemetry } from "@ai-sdk/otel";
import { VercelAIInstrumentor } from "@respan/instrumentation-vercel";
import { Respan } from "@respan/respan";
import { registerTelemetry } from "ai";

registerTelemetry(
  new OpenTelemetry({
    enrichSpan: () => ({
      "ai.telemetry.metadata.customer_identifier": "user-123",
      "ai.telemetry.metadata.thread_identifier": "thread-abc",
      "ai.telemetry.metadata.trace_group_identifier": "onboarding-flow",
    }),
  })
);

const respan = new Respan({
  instrumentations: [
    new VercelAIInstrumentor({ autoRegisterAISDKTelemetry: false }),
  ],
});
await respan.initialize();

With propagateAttributes

Set the user and conversation per request. All AI SDK calls within the scope inherit these attributes. This tags the spans the AI SDK reports and adds none of its own.

TypeScript
import { Respan } from "@respan/respan";
import { VercelAIInstrumentor } from "@respan/instrumentation-vercel";

const respan = new Respan({
  instrumentations: [new VercelAIInstrumentor()],
});
await respan.initialize();

async function handleRequest(userId: string, message: string) {
  return respan.propagateAttributes(
    {
      customer_identifier: userId,
      thread_identifier: "conv_abc_123",
      metadata: { plan: "pro" },
    },
    async () => {
      const result = await generateText({
        model: openai("gpt-4.1-nano"),
        prompt: message,
        telemetry: { isEnabled: true },
      });
      return result.text;
    }
  );
}
AttributeTypeDescription
customer_identifierstringIdentifies the end user in Respan analytics.
thread_identifierstringGroups related messages into a conversation.
metadataRecord<string, string>Custom key-value pairs attached to spans.

Examples

Streaming with tools

TypeScript
import { stepCountIs, streamText, tool } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

const result = streamText({
  model: openai("gpt-4.1-nano"),
  messages: [{ role: "user", content: "What's the weather in Paris?" }],
  tools: {
    getWeather: tool({
      description: "Get weather for a city",
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => `${city}: sunny, 72F`,
    }),
  },
  stopWhen: stepCountIs(5),
  telemetry: { isEnabled: true },
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

AI SDK 4.x-6.x

Keep @respan/instrumentation-vercel current, omit @ai-sdk/otel, and enable the legacy request telemetry option:

TypeScript
const result = await generateText({
  model: openai("gpt-4.1-nano"),
  prompt: "Tell me a joke about AI",
  experimental_telemetry: {
    isEnabled: true,
    metadata: { customer_identifier: "user-123" },
  },
});

The debug message Total instrumentations ready for SDK: 0 refers to legacy Traceloop auto-discovery. It does not mean VercelAIInstrumentor failed to load; that plugin is registered explicitly in Respan({ instrumentations: [...] }).