Trace Vercel AI SDK agents with OpenTelemetry

The AI SDK emits OpenTelemetry spans for every generateText, streamText and ToolLoopAgent call. Register its telemetry once, pass your chat id on each call, and Maple groups the spans into one agent session per conversation.

invoke_agent support_agent 5 spans · 3.12s
DurationStatus
invoke_agent support_agentsupport-agent
3.12sOk
chat gpt-4o-mini
940msOk
execute_tool lookup_order
180msOk
/api/orders/{id}orders-api
150msOk
chat gpt-4o-mini
1.95sOk

Example: an AI SDK agent turn with a tool call

Quick start

Set up Vercel AI SDK

1

Install the packages

bash
npm install ai@^7.0.106 @ai-sdk/otel @opentelemetry/sdk-node
2

Point the exporter at Maple

bash
export OTEL_SERVICE_NAME="support-agent"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=production"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.maple.dev"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_INGEST_KEY"
3

Register the AI SDK integration

typescript
// instrumentation.ts: import it first in your entry point
import { OpenTelemetry } from "@ai-sdk/otel"
import { NodeSDK } from "@opentelemetry/sdk-node"
import { registerTelemetry } from "ai"

// Reads OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES and OTEL_EXPORTER_OTLP_*
export const sdk = new NodeSDK()
sdk.start()

registerTelemetry(
	new OpenTelemetry({
		usage: true,
		runtimeContext: true,
	}),
)
4

Pass the conversation id on every call

typescript
import { streamText } from "ai"

const result = streamText({
	model,
	messages,
	runtimeContext: { conversationId: chatId },
	telemetry: { functionId: "support_agent", includeRuntimeContext: { conversationId: true } },
})

This is the short path. The full Vercel AI SDK guide covers the rest.

Organization in the EU region? Send to https://ingest.eu.maple.dev instead of https://ingest.maple.dev. An ingest key only works in its own region.

What you get

What Maple shows for an AI SDK agent

One session per conversation

Calls that share a conversation id form one agent session, with one turn per call.

Transcript

Each turn shows the prompts, the replies and the tool calls in the order they ran.

Agent names

functionId becomes the agent name, so two agents in one app stay apart. Sub-agents called from a tool keep their own functionId.

Token usage

usage: true records input and output tokens per model call. Cost shows as unpriced, because the AI SDK does not report it.

Tool failures

A tool that throws from execute is marked as failed on its span. A tool that returns an error value looks successful.

Prompts you choose to hide

Set recordInputs: false and recordOutputs: false on a call to keep its prompts and replies out of Maple.

What is different in AI SDK 7

Nothing is traced by default

In AI SDK 7, experimental_telemetry alone does nothing. Call registerTelemetry() once at startup; a second call emits every span twice.

ToolLoopAgent takes the id differently

It has no per-call runtimeContext. Declare conversationId in callOptionsSchema and map it to runtime context in prepareCall.

Streams and serverless

A stream's spans end when it is read to the end. Return the stream as the response, and call forceFlush() in a finally block in serverless handlers.

통합

다른 통합

오늘 첫 트레이스를 확인하세요.

SDK를 추가하고 OTLP 익스포터를 Maple로 향하게 하면 트레이스가 도착합니다.

maple.dev: OpenTelemetry 위의 옵저버빌리티