What is Vercel AI SDK Observability?
Vercel AI SDK observability gives you visibility into AI function calls, request durations, inputs, outputs, and custom metadata across your Next.js application. This guide covers setting up OpenTelemetry instrumentation to capture traces and spans from the Vercel AI SDK and stream that data to SigNoz.
With full Vercel AI SDK observability in SigNoz, you can trace AI interactions end-to-end, debug latency, set alerts on degraded performance, and improve the reliability of your AI features. This is especially valuable for production-grade Vercel observability where visibility into model behavior and user interactions is critical.
Explore the SigNoz Vercel AI SDK example chatbot, which includes observability and monitoring via OpenTelemetry.
Prerequisites
-
Next.js app
-
Vercel AI SDK integrated into the app
-
SigNoz setup (choose one): SigNoz Cloud accountwith an active ingestion key- Self-hosted SigNoz instance
-
Network access from your app to the chosen SigNoz endpoint
Instrument your Next.js App with OpenTelemetry
For detailed OpenTelemetry instrumentation instructions for Next.js, see the Next.js OpenTelemetry instrumentation guide.
Configure Vercel AI SDK Observability with OpenTelemetry
Step 1. Install OpenTelemetry packages
npm install @vercel/otel @opentelemetry/api
Step 2. Update ** next.config.mjs** to include instrumentationHook
This step is only needed when using NextJs 14 and below
/** @type {import('next').NextConfig} */
const nextConfig = {
// include instrumentationHook experimental feature
experimental: {
instrumentationHook: true,
},
}
export default nextConfig
Step 3. Create ** instrumentation.ts** file(in root project directory)
import { registerOTel, OTLPHttpJsonTraceExporter } from '@vercel/otel'
// Add otel logging
import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR) // set diaglog level to DEBUG when debugging
export function register() {
registerOTel({
serviceName: '<service_name>',
traceExporter: new OTLPHttpJsonTraceExporter({
url: 'https://ingest.<region>.signoz.cloud:443/v1/traces',
headers: { 'signoz-ingestion-key': '<your-ingestion-key>' },
}),
})
}
is the name of your service<service_name>
: Your SigNoz Cloud<region>
region: Your SigNoz<your-ingestion-key>
ingestion key
The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app.
Using self-hosted SigNoz? Most steps are identical. To adapt this guide, update the endpoint and remove the ingestion key header as shown in Cloud → Self-Hosted.
Your Next.js app is now properly instrumented.
Step 4. Verify Instrumentation Locally
Run your Next.js application in development mode:
npm run dev
OpenTelemetry output appears in the terminal when the application starts, confirming that the instrumentation.ts file was loaded correctly.
To see detailed trace export logs, you can temporarily set the DiagLogLevel to DEBUG in instrumentation.ts:
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG)
Enable Vercel AI SDK Telemetry
The Vercel AI SDK uses OpenTelemetry to collect telemetry data. OpenTelemetry is an open-source observability framework designed to provide standardized instrumentation for collecting telemetry data.
Enabling Telemetry
For more detail on available telemetry options, see the Vercel AI SDK telemetry documentation.
You can then use the experimental_telemetry
option to enable telemetry on specific function calls while the feature is experimental:
const result = await generateText({
model: openai('gpt-4-turbo'),
prompt: 'Write a short story about a cat.',
experimental_telemetry: { isEnabled: true },
})
When telemetry is enabled, you can also control whether you want to record the input values and the output values for the function. By default, both are enabled. You can disable them by setting the recordInputs
and recordOutputs
options to false
.
experimental_telemetry: { isEnabled: true, recordInputs: false, recordOutputs: false}
Disabling the recording of inputs and outputs can be useful for privacy, data transfer, and performance reasons. You might, for example, want to disable recording inputs if they contain sensitive information.
Telemetry Metadata
You can provide a functionId
to identify the function that the telemetry data is for, and metadata
to include additional information in the telemetry data.
const result = await generateText({
model: openai('gpt-4-turbo'),
prompt: 'Write a short story about a cat.',
experimental_telemetry: {
isEnabled: true,
functionId: 'my-awesome-function',
metadata: {
something: 'custom',
someOtherThing: 'other-value',
},
},
})
Custom Tracer
You can provide a tracer
which must return an OpenTelemetry Tracer
. This is useful in situations where you want your traces to use a TracerProvider
other than the one provided by the @opentelemetry/api
singleton.
const tracerProvider = new NodeTracerProvider()
const result = await generateText({
model: openai('gpt-4-turbo'),
prompt: 'Write a short story about a cat.',
experimental_telemetry: {
isEnabled: true,
tracer: tracerProvider.getTracer('ai'),
},
})
Once configured, your Vercel AI SDK commands automatically emit traces, spans, and events. See the Vercel AI SDK collected data reference for details on the types of spans and events generated.
Vercel AI SDK traces are available in SigNoz under the Traces tab:
If you click on any span, you can see the detailed trace of which it is a part of.
Vercel AI SDK Observability Dashboard
The Vercel AI SDK Observability Dashboard provides specialized visualizations for monitoring your AI applications. The dashboard includes pre-built charts and metrics specifically tailored for Vercel AI SDK telemetry data, along with import instructions to get started quickly.