Start
Lilium
Guides
Connect

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.

August 4, 2026Beginner10 minutes

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.

  1. Install the telemetry packages.

    npm install @lilium/otel @ai-sdk/otel @opentelemetry/sdk-node
  2. Create instrumentation.ts at 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.