Trace a Vercel AI SDK app
Turn on AI SDK telemetry and route its spans into Lilium, including tool calls and multi-step agent runs.
Before you start
- A Next.js app using the AI SDK
- An Lilium project API key
The AI SDK emits OpenTelemetry spans natively. The work here is switching them on and giving them somewhere to go.
#Register instrumentation
Next.js loads instrumentation.ts before any route handler runs. That is where the exporter
belongs.
-
Install the telemetry packages.
npm install @lilium/otel @ai-sdk/otel @opentelemetry/sdk-node -
Create
instrumentation.tsat the project root.import { OpenTelemetry } from '@ai-sdk/otel' import { NodeSDK } from '@opentelemetry/sdk-node' import { registerTelemetry } from 'ai' import { createLiliumSpanProcessor, liliumResource } from '@lilium/otel' export function register() { new NodeSDK({ resource: liliumResource({ serviceName: 'checkout-backend', environment: process.env.NODE_ENV, }), spanProcessors: [ createLiliumSpanProcessor({ apiKey: process.env.LILIUM_API_KEY, endpoint: process.env.LILIUM_OTLP_URL, }), ], }).start() registerTelemetry(new OpenTelemetry({ usage: true, runtimeContext: true, enrichSpan: ({ runtimeContext }) => { const context = runtimeContext as Record<string, unknown> | undefined return { 'lilium.agent_id': context?.agentId, 'lilium.agent_role': context?.agentRole, 'lilium.user_id': context?.userId, } }, })) }
#Identify each call
AI SDK 7 emits telemetry after registration. Use runtimeContext for run identity and
telemetry.functionId for the stable operation name.
import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'
const result = await generateText({
model: openai('gpt-5-mini'),
prompt,
tools,
runtimeContext: {
agentId: 'checkout.assistant',
agentRole: 'checkout',
userId: customer.id,
},
telemetry: {
functionId: 'checkout.summarize-order',
includeRuntimeContext: {
agentId: true,
agentRole: true,
userId: true,
},
recordInputs: true,
recordOutputs: true,
},
})Multi-step calls produce child spans, so the trace shows the model and tool work that happened between the request and final output.
#Trace streaming responses
streamText works the same way. The span closes when the stream finishes rather than when the
function returns, so duration reflects the real user-visible time.
const stream = await streamText({
model: openai('gpt-5-mini'),
prompt,
telemetry: { functionId: 'checkout.draft-reply' },
})#Verify the trace
Trigger the route once. You should see one span per AI SDK call, with tool steps nested beneath it and token usage recorded on each model step.
If you see the request span but no model spans, confirm the AI SDK telemetry registration ran
before the route imported its model code. AI SDK 5 and 6 additionally require
experimental_telemetry.isEnabled: true on each call.
#Where to go next
Send OpenTelemetry spans covers routing these spans through an existing collector, and Traces and spans explains what Lilium does with them once they land.
Common questions
This setup uses the OpenTelemetry Node SDK and therefore requires the Node.js runtime. Edge instrumentation needs a runtime-compatible OpenTelemetry provider.
Confirm registerTelemetry runs before the first AI SDK call and that @ai-sdk/otel is configured. For AI SDK 5 or 6, experimental_telemetry must also be enabled per call.
Yes. telemetry.functionId identifies the operation, so use a stable product action such as support.reply rather than a handler filename.