Quickstart: tracepilot-vercel

Instrument Vercel AI SDK with full observability in under 5 minutes. Trace generateText, streamText, and tool calls — then replay failures from the dashboard.

Go from install to live trace in under 5 minutes. This guide covers everything you need to add TracePilot observability to a Vercel AI SDK project.

Prerequisites

• A Next.js or Node.js project using the Vercel AI SDK (ai package)
• An OpenAI API key (or any AI SDK-compatible provider)
• Node.js 18+

1. Install

npm

npm install tracepilot-vercel

2. Add your API key

Get your key from tracepilotai.com → Account Settings. It looks like tp_live_xxxxxxxxxxxxxxxx.

.env.local

TRACEPILOT_API_KEY=tp_live_xxxxxxxxxxxxxxxx

For production, add this in your Vercel project settings → Environment Variables. Never commit it to source control.

3. Initialize

Create a single TracePilot instance and reuse it across your app.

lib/tracepilot.ts

import { TracePilotVercel } from 'tracepilot-vercel';

export const tp = new TracePilotVercel(process.env.TRACEPILOT_API_KEY!);

4. Trace generateText

app/api/generate/route.ts

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { tp } from '@/lib/tracepilot';

export async function POST(req: Request) {
  const { prompt } = await req.json();

  await tp.startTrace('generate-route');

  const { result, spanId } = await tp.wrapGenerate(
    () => generateText({
      model: openai('gpt-4o'),
      prompt,
    }),
    { prompt },
    undefined, // root span
    1
  );

  return Response.json({ text: result.text });
}

5. Trace streamText

app/api/chat/route.ts

import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { StreamingTextResponse } from 'ai';
import { tp } from '@/lib/tracepilot';

export async function POST(req: Request) {
  const { messages } = await req.json();

  await tp.startTrace('chat-route');

  const { stream } = await tp.wrapStream(
    () => streamText({
      model: openai('gpt-4o'),
      messages,
    }),
    messages,
    undefined,
    1
  );

  // Stream is returned to the client unchanged.
  // TracePilot captures it in the background.
  return new StreamingTextResponse(stream);
}

wrapStream does not buffer or delay the stream. Time-to-first-token is unaffected.

Expected trace output

After running your app, open tracepilotai.com/dashboard. You should see:

└─ generate-route                        [trace]
   └─ Span 1 — generateText               1.2s  ✓
         model: gpt-4o
         prompt_tokens: 48
         completion_tokens: 120
         cost: $0.0018

For streaming:

└─ chat-route                            [trace]
   └─ Span 1 — streamText                 0.8s ✓
         model: gpt-4o
         first_token_latency: 230ms
         prompt_tokens: 112
         completion_tokens: 88

Troubleshooting

Trace not appearing in dashboard

• Confirm TRACEPILOT_API_KEY is set. Run console.log(process.env.TRACEPILOT_API_KEY) to verify it’s loaded.
• Make sure tp.startTrace() is called before any wrapGenerate or wrapStream call.
• Check that you’re not using .env instead of .env.local for local dev.

streamText span shows empty output

Pass the wrapped stream (returned by tp.wrapStream) to StreamingTextResponse — not the raw result from streamText. TracePilot reads from the stream tap; passing the raw stream skips the instrumentation.

TypeError: Cannot read properties of undefined (reading 'startTrace')

The TracePilotVercel instance is undefined. This usually means TRACEPILOT_API_KEY is not set. The constructor receives undefined and throws lazily. Add a startup assertion:

if (!process.env.TRACEPILOT_API_KEY) throw new Error('TRACEPILOT_API_KEY is not set');

Spans appear in dashboard but no cost data

Cost tracking requires the model name to be recognized. Ensure you’re passing a standard OpenAI model string (gpt-4o, gpt-4o-mini, etc.). Custom fine-tuned model names are not mapped automatically.

Next steps

Debugging Vercel AI SDK

Step-by-step guide to debugging generateText, streamText, and tool calls in production.

Multi-step agents

Chain spans with parentSpanId to trace complex pipelines.

Time-travel debugging

Fork any failing span and replay it without redeploying.

Cost tracking

Monitor token spend across every AI SDK call.