Vercel AI SDK (tracing)
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, token usage, and multi-step workflow structure when AI SDK telemetry is enabled.
Set up Respan
Create an account at platform.respan.ai and grab an API key.
Run npx @respan/cli setup to set up with your coding agent.
Use Respan Gateway
See Vercel AI SDK gateway setup to route this integration through the Respan gateway.
Example projects
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.
Set environment variables
OPENAI_API_KEY is used for LLM requests. RESPAN_API_KEY is used to export traces to Respan.
Initialize Respan
Next.js
Serverless / Node
Create instrumentation.ts in your project root (same level as package.json). Next.js calls register() automatically at startup.
Then add serverExternalPackages to next.config.ts:
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.
View your trace
Open the Traces page to see your AI calls with input/output, token usage, and tool calls.
Configuration
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.
With propagateAttributes
Override per-request using a context scope. All AI SDK calls within the scope inherit these attributes.
Decorators (optional)
Decorators are not required. After the AI SDK 7 OpenTelemetry bridge is registered and request telemetry is enabled, model and tool operations emit spans automatically. Use withWorkflow and withTask to group AI calls into named workflows with nested tasks.
Examples
Streaming with tools
AI SDK 4.x-6.x
Keep @respan/instrumentation-vercel current, omit @ai-sdk/otel, and enable the legacy request telemetry option:
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: [...] }).