Docs
DocumentationQuery ReferenceAPI Reference
Open Console→→
DocumentationQuery ReferenceAPI Reference

Platform overview

What is Axiom?QuickstartArchitectureFeatures
Fundamentals
Datasets
Edge deployments
Limits
Performance
Optimize usage
Requirements
Semantic conventions
Glossary
Tour
SecurityRoadmap

Send data

Reference architecturesMethods

Understand data

Console
Query
Builder
Editor
Query results
Visualize
Traces
Metrics
Correlations
Save queries
Stream
Dashboard
Create
Elements
Create
Configure
Element types
Gauge
Heatmap
Log stream
Monitor list
Note
Pie chart
Scatter plot
Statistic
Table
Time series
Sections
Configure
Filter
Monitor
Overview
View status
Configure
Examples
Monitor types
Anomaly
Match
New values
Threshold
Alerting
Overview
Configure
Notifier types
Amp
ChatGPT Workspace Agent
Claude Code
Cursor
Custom Webhook
Discord
Email
incident.io
Jira Service Management
Microsoft Teams
Opsgenie
PagerDuty
Slack
Annotations
Command Menu
Manage
Datasets
Overview
Views
Virtual fields
Access
RBAC
Tokens
CLI
Organization
Labels
Audit log
Settings
Usage and billing
Profile
Extend
Overview
AWS Lambda
AWS PrivateLink
Cloudflare Workers
Cloudflare Logpush
Convex
Grafana
Hex
Netlify
Supabase
Tailscale
Terraform
Unkey
Vercel
Intelligence
Overview
Spotlight
AI agents
Overview
MCP Server
Overview
Tools
Query cost limits
Agent-created orgs
Skills
Overview
Axiom alerting
Build dashboards
Control costs
SRE
Translate SPL to APL
Splunk
Overview
Splunk app
Install and configure
Commands
Traces
Examples
Portal
How it works
Set up standard mode
Set up transparent mode
Observability Cloud
OCSF data
OCSF as CIM
SPL command support
Examples
Monitor and troubleshoot

Use cases

ObservabilityProduct analytics
OCSF security data
Overview
Send data
Query data
LLM observability
Overview
Use Vercel AI SDK
Manual instrumentation
OpenAI Agents SDK
GenAI attributes
Redaction policies

Miscellaneous

LLMs
Overview
List of docs pages
Full docs
Query reference
FAQs
Legal
Acceptable use policy
Axiom for Startups terms
Committed use terms
Cookies
Data processing
HIPAA
Partner agreement
Partner program guide
Privacy policy
SLA
Terms of service
Terms of use
Use cases/LLM observability

Instrument Vercel AI SDK apps

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 versionInstrumentationAxiom package required
7Built-in AI SDK telemetryNo
4, 5, and 6Axiom AI SDK wrappersYes, axiom

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.

Alternatively, instrument your app manually. For more information on instrumentation approaches, see LLM observability.

Prerequisites

  1. Install the OpenTelemetry packages:

    shell
    npm i @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions
  2. 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.

Export traces to Axiom

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');
      }
    }

Instrument AI SDK 7

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.

  1. Install Vercel AI SDK, a provider, and the AI SDK OpenTelemetry integration:

    shell
    npm i ai @ai-sdk/openai @ai-sdk/otel
  2. 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 section
    
    registerTelemetry(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.

Instrument AI SDK 4, 5, and 6

For Vercel AI SDK 4, 5, and 6, use Axiom AI SDK to wrap your models and tools.

Info

Axiom AI SDK is an open-source project and welcomes your contributions. For more information, see the GitHub repository.

Warning

Axiom AI SDK doesn’t instrument Vercel AI SDK 7 models. If you pass one to wrapAISDKModel or axiomAIMiddleware, Axiom AI SDK logs a warning and sends no spans. Use the built-in AI SDK 7 telemetry instead.

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.

Initialize Axiom AI SDK

  1. Install Axiom AI SDK and Zod:

    shell
    npm i axiom zod
  2. 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 section
    
    const 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.

Wrap models

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.

  1. 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
  2. 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 tracing
    export const gpt4o = wrapAISDKModel(openaiProvider('gpt-4o'));
    export const gpt4oMini = wrapAISDKModel(openaiProvider('gpt-4o-mini'));
  1. 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
  2. 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 tracing
    export const claudeSonnet = wrapAISDKModel(anthropicProvider('claude-sonnet-4-5'));
    export const claudeHaiku = wrapAISDKModel(anthropicProvider('claude-haiku-4-5'));
  1. 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
  2. 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 tracing
    export const geminiFlash = wrapAISDKModel(geminiProvider('gemini-2.5-flash'));
    export const geminiPro = wrapAISDKModel(geminiProvider('gemini-2.5-pro'));
  1. 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
  2. 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 tracing
    export 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.

  1. Run the following in your terminal to install Vercel AI SDK 6:

    shell
    npm i ai@ai-v6
  2. 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 tracing
    export const gpt4o = wrapAISDKModel(gateway('openai/gpt-4o'));

Use axiomAIMiddleware with wrapLanguageModel

If you already compose middleware with the Vercel AI SDK’s wrapLanguageModel, pass axiomAIMiddleware({ model }) instead of calling wrapAISDKModel:

typescript
import { wrapLanguageModel } from 'ai';
import { createOpenAI } from '@ai-sdk/openai';
import { axiomAIMiddleware } from 'axiom/ai';

const openaiProvider = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const baseModel = openaiProvider('gpt-4o');

export const gpt4o = wrapLanguageModel({
  model: baseModel,
  middleware: [axiomAIMiddleware({ model: baseModel })],
});

The rest of this section explains how to work with OpenAI. The process is similar for other LLMs.

Add context

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>;
}

Instrument tool calls

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 tools
const { 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,
});

Complete example

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 client
const 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:

  1. wrapAISDKModel: Automatically captures telemetry for the LLM provider call
  2. wrapTool: Instruments the tool execution with detailed spans
  3. withSpan: Creates a parent span that ties everything together under a business capability

What’s next?

After sending traces to Axiom:

  • View your traces in Console
  • Set up monitors and alerts based on your AI telemetry data
  • Learn about the GenAI APL functions for querying AI telemetry
Was this page helpful?
Suggest edits on GitHub
PreviousLLM observabilityNextManual instrumentation
On this page
PrerequisitesExport traces to AxiomInstrument AI SDK 7Instrument AI SDK 4, 5, and 6Initialize Axiom AI SDKWrap modelsUse axiomAIMiddleware with wrapLanguageModelAdd contextInstrument tool callsComplete exampleWhat’s next?