Vercel AI SDK

AI SDK 7 emits GenAI semantic-convention spans through @ai-sdk/otel, covering agent runs, steps, tool calls, the system prompt, prompts and output.

New to Oodle?

Oodle is a managed observability platform for metrics, logs, traces and agent traces. It ingests OpenTelemetry natively, so the snippet on this page is the complete setup.

Each trace shows the full transcript, the token counts and cost of every call, the agent structure (runs, steps and tool calls) and Signals: labels for loops, rate limits, refusals and tool failures, detected as the trace arrives.

Sign up for free to get an instance ID and an API key, or see the Agent Observability overview first.

You will need:

• OODLE_INSTANCE: your Oodle instance ID (ap1, us1)
• OODLE_API_KEY: an Oodle API key (ap1, us1)
• OTLP_ENDPOINT: your OTLP collector domain, shown on the tile

Open the Vercel AI SDK tile on the ap1, us1 page to get these filled in for you, or let an agent do the setup with /oodle-onboarding set up the llm_observability_vercel integration.

Install

Install the AI SDK OpenTelemetry integration alongside the OTel SDK:

npm install ai @ai-sdk/otel \
  @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node \
  @opentelemetry/resources @opentelemetry/semantic-conventions

Instrument

Register the OpenTelemetry integration once at startup. Every AI SDK call then emits GenAI semantic-convention spans, with no per-call flag:

// instrumentation.ts
import { registerTelemetry } from 'ai';
import { OpenTelemetry } from '@ai-sdk/otel';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';

// NodeTracerProvider does not read OTEL_SERVICE_NAME, so name
// the service here or every trace lands under
// unknown_service:node.
export const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: 'my-llm-app' }),
  spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter())],
});

provider.register();

// AI SDK 7 moved OpenTelemetry out of the `ai` package into
// @ai-sdk/otel. Registering the integration turns telemetry on
// for every call: there is no per-call experimental_telemetry
// flag any more, and passing one traces nothing.
registerTelemetry(new OpenTelemetry());

// index.ts - import the instrumentation first.
import { provider } from './instrumentation';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

async function main() {
  const { text } = await generateText({
    model: openai('gpt-4o-mini'),
    system: 'You are a helpful assistant.',
    prompt: 'Hello!',
  });
  console.log(text);

  // Short-lived processes must flush before they exit.
  await provider.forceFlush();
}

main();

Environment

Point the application at Oodle:

# OTLP endpoint (points straight at Oodle)
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<OTLP_ENDPOINT>

export OTEL_EXPORTER_OTLP_HEADERS="X-API-KEY=<OODLE_API_KEY>,X-OODLE-INSTANCE=<OODLE_INSTANCE>"

# Compress the export: prompt payloads are large
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip

Verify

Run your application, then open ap1, us1. Spans carry gen_ai.* attributes: the model, token counts, and the prompt and response content. Click a trace for the Transcript, the waterfall, and the cost breakdown.

If nothing arrives, check that the exporter can reach https://<OTLP_ENDPOINT> and that the instance and key are set: the OTLP gateway answers 401 without them.