Learn how to send AI telemetry from your TypeScript app to Axiom with the built-in telemetry of Vercel AI SDK 7 or with Axiom AI SDK for earlier versions.
This page explains how to send telemetry from a TypeScript generative AI app built with Vercel AI SDK to Axiom.
How you instrument your app depends on your version of Vercel AI SDK:
Vercel AI SDK 7 emits OpenTelemetry spans with the GenAI semantic conventions natively, so you only need to export them to Axiom. Earlier versions need Axiom AI SDK to create these spans.
npm i @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions
Set the AXIOM_TOKEN and AXIOM_DATASET environment variables using an API token with ingest permission and the name of the dataset where you send telemetry.
Both instrumentation methods write spans to the global OpenTelemetry API. Register a NodeTracerProvider with an OTLPTraceExporter that sends spans to Axiom. Replace AXIOM_DOMAIN with the domain for your dataset.
typescript
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';import { resourceFromAttributes } from '@opentelemetry/resources';import { BatchSpanProcessor, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';const exporter = new OTLPTraceExporter({ url: 'https://AXIOM_DOMAIN/v1/traces', headers: { Authorization: `Bearer ${process.env.AXIOM_TOKEN}`, 'X-Axiom-Dataset': process.env.AXIOM_DATASET!, },});const provider = new NodeTracerProvider({ resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: 'my-ai-app', }), spanProcessors: [new BatchSpanProcessor(exporter)],});provider.register();
Load this file once at application startup, before your app makes any LLM calls:
In a Node.js app, import it at the top of your entry file: import './instrumentation.node';
In a Next.js app, import it from the register function in src/instrumentation.ts. Next.js also loads this file in the Edge runtime, so import the Node.js setup only in the Node.js runtime:
typescript
export async function register() { if (process.env.NEXT_RUNTIME === 'nodejs') { await import('./instrumentation.node'); }}
Vercel AI SDK 7 creates spans for model calls, tool executions, and agent steps through its OpenTelemetry integration. You don’t need Axiom AI SDK.
Install Vercel AI SDK, a provider, and the AI SDK OpenTelemetry integration:
shell
npm i ai @ai-sdk/openai @ai-sdk/otel
Register the integration at the end of src/instrumentation.node.ts, after provider.register():
typescript
import { OpenTelemetry } from '@ai-sdk/otel';import { registerTelemetry } from 'ai';// ...exporter and provider setup from the previous sectionregisterTelemetry(new OpenTelemetry());
After you register the integration, AI SDK calls emit telemetry by default. You don’t need to wrap models or tools. To group spans by feature, set telemetry.functionId. AI SDK records it as gen_ai.agent.name.
typescript
import { openai } from '@ai-sdk/openai';import { generateText, stepCountIs, tool } from 'ai';import { z } from 'zod';export default async function Page() { const { text } = await generateText({ model: openai('gpt-4o'), telemetry: { functionId: 'get_directions' }, stopWhen: stepCountIs(5), messages: [{ role: 'user', content: 'How do I get from Paris to Berlin?' }], tools: { findDirections: tool({ description: 'Find directions to a location', inputSchema: z.object({ from: z.string(), to: z.string() }), execute: async ({ from, to }) => ({ directions: `To get from ${from} to ${to}, use a teleporter.`, }), }), }, }); return <p>{text}</p>;}
AI SDK records prompts, responses, tool arguments, and tool results by default. To exclude them from a call, set telemetry: { recordInputs: false, recordOutputs: false }. To turn off telemetry for a call, set telemetry: { isEnabled: false }. For more information, see the AI SDK telemetry documentation.
For Vercel AI SDK 4, 5, and 6, use Axiom AI SDK to wrap your models and tools.
The examples in this section use Vercel AI SDK 6. Version 5 uses the same code. For Vercel AI SDK 4, replace inputSchema with parameters in tool definitions, and replace stopWhen: stepCountIs(5) with maxSteps: 5.
At the end of src/instrumentation.node.ts, after provider.register(), create a tracer and pass it to initAxiomAI:
typescript
import { trace } from '@opentelemetry/api';import { initAxiomAI, RedactionPolicy } from 'axiom/ai';// ...exporter and provider setup from the previous sectionconst tracer = trace.getTracer('my-ai-app');initAxiomAI({ tracer, redactionPolicy: RedactionPolicy.AxiomDefault });
Axiom AI SDK doesn’t read AXIOM_TOKEN or AXIOM_DATASET directly. The exporter you registered sends its spans to Axiom. For redaction options, see Redaction policies.
The wrapAISDKModel function takes an existing AI model object and returns an instrumented version that automatically generates trace data for every call.
Choose one of the following common Vercel AI SDK providers. For the full list of providers, see the Vercel documentation.
Run the following in your terminal to install Vercel AI SDK 6 and the OpenAI provider:
shell
npm i ai@ai-v6 @ai-sdk/openai@ai-v6
Create the file src/shared/openai.ts with the following content:
typescript
import { createOpenAI } from '@ai-sdk/openai';import { wrapAISDKModel } from 'axiom/ai';const openaiProvider = createOpenAI({ apiKey: process.env.OPENAI_API_KEY,});// Wrap the model to enable automatic tracingexport const gpt4o = wrapAISDKModel(openaiProvider('gpt-4o'));export const gpt4oMini = wrapAISDKModel(openaiProvider('gpt-4o-mini'));
Run the following in your terminal to install Vercel AI SDK 6 and the Anthropic provider:
shell
npm i ai@ai-v6 @ai-sdk/anthropic@ai-v6
Create the file src/shared/anthropic.ts with the following content:
typescript
import { createAnthropic } from '@ai-sdk/anthropic';import { wrapAISDKModel } from 'axiom/ai';const anthropicProvider = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY,});// Wrap the model to enable automatic tracingexport const claudeSonnet = wrapAISDKModel(anthropicProvider('claude-sonnet-4-5'));export const claudeHaiku = wrapAISDKModel(anthropicProvider('claude-haiku-4-5'));
Run the following in your terminal to install Vercel AI SDK 6 and the Gemini provider:
shell
npm i ai@ai-v6 @ai-sdk/google@ai-v6
Create the file src/shared/gemini.ts with the following content:
typescript
import { createGoogleGenerativeAI } from '@ai-sdk/google';import { wrapAISDKModel } from 'axiom/ai';const geminiProvider = createGoogleGenerativeAI({ apiKey: process.env.GEMINI_API_KEY,});// Wrap the model to enable automatic tracingexport const geminiFlash = wrapAISDKModel(geminiProvider('gemini-2.5-flash'));export const geminiPro = wrapAISDKModel(geminiProvider('gemini-2.5-pro'));
Run the following in your terminal to install Vercel AI SDK 6 and the Grok provider:
shell
npm i ai@ai-v6 @ai-sdk/xai@ai-v6
Create the file src/shared/grok.ts with the following content:
typescript
import { createXai } from '@ai-sdk/xai';import { wrapAISDKModel } from 'axiom/ai';const grokProvider = createXai({ apiKey: process.env.XAI_API_KEY,});// Wrap the model to enable automatic tracingexport const grok4 = wrapAISDKModel(grokProvider('grok-4'));export const grok3Mini = wrapAISDKModel(grokProvider('grok-3-mini'));
To instrument calls without a Vercel AI SDK provider, use the generic Vercel AI Gateway provider.
To instrument calls without a Vercel AI SDK provider, use the generic Vercel AI Gateway provider. Vercel AI SDK 4 doesn’t include the gateway provider. For more information, see the Vercel documentation.
Run the following in your terminal to install Vercel AI SDK 6:
shell
npm i ai@ai-v6
Create the file src/shared/openai.ts with the following content:
typescript
import { createGateway } from 'ai';import { wrapAISDKModel } from 'axiom/ai';const gateway = createGateway({ apiKey: process.env.AI_GATEWAY_API_KEY,});// Wrap the model to enable automatic tracingexport const gpt4o = wrapAISDKModel(gateway('openai/gpt-4o'));
The withSpan function allows you to add crucial business context to your traces. It creates a parent span around your LLM call and attaches metadata about the capability and step that you execute.
typescript
import { withSpan } from 'axiom/ai';import { generateText } from 'ai';import { gpt4o } from '@/shared/openai';export default async function Page() { const userId = 123; // Use withSpan to define the capability and step const res = await withSpan({ capability: 'get_capital', step: 'generate_answer' }, (span) => { // You have access to the OTel span to add custom attributes span.setAttribute('user_id', userId); return generateText({ model: gpt4o, // Use the wrapped model messages: [ { role: 'user', content: 'What is the capital of Spain?', }, ], }); }); return <p>{res.text}</p>;}
For many AI capabilities, the LLM call is only part of the story. If your capability uses tools to interact with external data or services, observing the performance and outcome of those tools is critical. Axiom AI SDK provides the wrapTool and wrapTools functions to automatically instrument your Vercel AI SDK tool definitions.
The wrapTool helper takes your tool’s name and its definition and returns an instrumented version. This wrapper creates a dedicated child span for every tool execution, capturing its arguments, output, and any errors.
By default, generateText stops after the first step. To let the model answer after it calls a tool, set stopWhen.
typescript
import { generateText, stepCountIs, tool } from 'ai';import { z } from 'zod';import { wrapTool } from 'axiom/ai';import { gpt4o } from '@/shared/openai';// In your generateText call, provide wrapped toolsconst { text, toolResults } = await generateText({ model: gpt4o, stopWhen: stepCountIs(5), messages: [ { role: 'system', content: 'You are a helpful assistant.' }, { role: 'user', content: 'How do I get from Paris to Berlin?' }, ], tools: { // Wrap each tool with its name findDirections: wrapTool( 'findDirections', // The name of the tool tool({ description: 'Find directions to a location', inputSchema: z.object({ from: z.string(), to: z.string(), }), execute: async (params) => { // Your tool logic here... return { directions: `To get from ${params.from} to ${params.to}, use a teleporter.` }; }, }) ) }});
To wrap several tools at once, pass a tool map to wrapTools:
typescript
import { generateText, stepCountIs, tool } from 'ai';import { wrapTools } from 'axiom/ai';import { z } from 'zod';import { gpt4o } from '@/shared/openai';const tools = wrapTools({ findDirections: tool({ description: 'Find directions to a location', inputSchema: z.object({ from: z.string(), to: z.string() }), execute: async ({ from, to }) => ({ directions: `To get from ${from} to ${to}, use a teleporter.`, }), }),});const { text } = await generateText({ model: gpt4o, stopWhen: stepCountIs(5), messages: [{ role: 'user', content: 'How do I get from Paris to Berlin?' }], tools,});
Example of how all three instrumentation functions work together in a single, real-world example:
typescript
import { withSpan, wrapAISDKModel, wrapTool } from 'axiom/ai';import { generateText, stepCountIs, tool } from 'ai';import { createOpenAI } from '@ai-sdk/openai';import { z } from 'zod';// 1. Create and wrap the AI model clientconst openaiProvider = createOpenAI({ apiKey: process.env.OPENAI_API_KEY,});const gpt4o = wrapAISDKModel(openaiProvider('gpt-4o'));// 2. Define and wrap your tool(s)const findDirectionsTool = wrapTool( 'findDirections', // The tool name must be passed to the wrapper tool({ description: 'Find directions to a location', inputSchema: z.object({ from: z.string(), to: z.string() }), execute: async ({ from, to }) => ({ directions: `To get from ${from} to ${to}, use a teleporter.`, }), }));// 3. In your application logic, use `withSpan` to add context// and call the AI model with your wrapped tools.export default async function Page() { const userId = 123; const { text } = await withSpan({ capability: 'get_directions', step: 'generate_ai_response' }, async (span) => { // You have access to the OTel span to add custom attributes span.setAttribute('user_id', userId); return generateText({ model: gpt4o, // Use the wrapped model stopWhen: stepCountIs(5), messages: [ { role: 'system', content: 'You are a helpful assistant.' }, { role: 'user', content: 'How do I get from Paris to Berlin?' }, ], tools: { findDirections: findDirectionsTool, // Use the wrapped tool }, }); }); return <p>{text}</p>;}
This demonstrates the three key steps to rich observability:
wrapAISDKModel: Automatically captures telemetry for the LLM provider call
wrapTool: Instruments the tool execution with detailed spans
withSpan: Creates a parent span that ties everything together under a business capability