@unhandled/instrumentation-vercel-ai
v1.0.14
Published
Vercel AI SDK telemetry normalized to GenAI conventions for Unhandled
Readme
@unhandled/instrumentation-vercel-ai
Turns Vercel AI SDK telemetry into GenAI-convention spans. The instrumentation switches experimental_telemetry on for you; the span processor renames and re-maps the spans the SDK emits. Neither creates spans of its own.
Covers generateText, streamText, generateObject, streamObject, embed, embedMany and rerank. Peer: ai >=3.0.0 <7.
Install
pnpm add @unhandled/instrumentation-vercel-aiRegister
With the AdonisJS agent:
import { vercelAi } from '@unhandled/instrumentation-vercel-ai/integration'
export default defineConfig({
integrations: [vercelAi({ recordInputs: true, recordOutputs: false })],
})Standalone:
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
import {
VercelAiInstrumentation,
VercelAiSpanProcessor,
} from '@unhandled/instrumentation-vercel-ai'
const provider = new NodeTracerProvider({ spanProcessors: [new VercelAiSpanProcessor()] })
provider.register()
new VercelAiInstrumentation().enable()Register before ai is imported. Nothing is traced until the instrumentation is enabled.
Options
| Option | Where | Default | Effect |
| --------------- | -------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| recordInputs | integration, instrumentation, processor | false | Prompt, system instructions, tool arguments. Integration value beats the per-call value. The processor defaults to true and keeps whatever the SDK recorded. |
| recordOutputs | integration, instrumentation, processor | false | Response text, tool calls, object, tool results. Same precedence and processor default. |
| enabled | integration | true | false skips the integration entirely. |
Content is opt-in: set the options above, or recordInputs / recordOutputs in a call's experimental_telemetry. A call with experimental_telemetry: { isEnabled: false } stays untraced. Pass the same recording options to the processor so content is also dropped from spans the SDK already recorded.
Conversation id
import { withConversationId, getConversationId } from '@unhandled/instrumentation-vercel-ai'
await withConversationId('chat-42', () => generateText({ ... }))
getConversationId() // 'chat-42' inside the callbackEvery span started inside gets gen_ai.conversation.id.
Span names
| Span | Name | Example |
| -------- | -------------------------- | ---------------------------- |
| pipeline | {operation} {functionId} | invoke_agent weather-app |
| model | {operation} {modelId} | generate_text gpt-4o |
| tool | execute_tool {toolName} | execute_tool getWeather |
Operations: invoke_agent (generateText, streamText), generate_object, stream_object, embeddings, rerank, generate_text / stream_text (model spans), execute_tool.
Attributes
- Always:
gen_ai.operation.name,gen_ai.request.model,gen_ai.response.model,gen_ai.provider.name,gen_ai.function_id,gen_ai.tool.name. - Model spans only:
gen_ai.usage.input_tokens,gen_ai.usage.output_tokens,gen_ai.usage.cache_read.input_tokens,gen_ai.usage.cache_write.input_tokens,gen_ai.usage.reasoning.output_tokens. Pipeline spans keep the summed usage asvercel.ai.usage.*. - Inputs (
recordInputs):gen_ai.system_instructions,gen_ai.input.messages,gen_ai.tool.call.arguments. - Outputs (
recordOutputs):gen_ai.output.messages,gen_ai.tool.call.result. - Every other
ai.*attribute is kept asvercel.ai.*, for examplevercel.ai.response.msToFirstChunk. - Tool results that embed an error (
tool-error,error-text,error-json,isError) add anexceptionevent and ERROR status to the tool span.
Model spans carry gen_ai.usage.cost only when the SDK reports ai.usage.cost. Otherwise Unhandled computes cost when it reads the spans, from the model's price on that day.
For AI agents
A coding agent can install this package, check that its data arrives and fix the errors it reports through the Unhandled MCP server at https://unhandled.net/mcp. In Claude Code, the Unhandled plugin adds that server plus skills for instrumenting a service, fixing a production error with a failing test first and verifying a deploy:
claude plugin marketplace add treboryx/unhandled
claude plugin install unhandled@unhandledCodex, Cursor, Gemini CLI and other agents connect to the same URL. Coding agents has the setup for each one and an AGENTS.md section to add to your repository.
