Quickstart: tracepilot-vercel

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 install tracepilot-vercel

yarn add tracepilot-vercel

pnpm add 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

Screenshot pending: Live trace in the TracePilot dashboard after a streamText call.

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.

Get Started

Core Concepts

Guides

Integrations

Quickstart: tracepilot-vercel

Prerequisites

1. Install

2. Add your API key

3. Initialize

4. Trace `generateText`

5. Trace `streamText`

Expected trace output

Troubleshooting

Next steps

Debugging Vercel AI SDK

Multi-step agents

Time-travel debugging

Cost tracking

​Prerequisites

​1. Install

​2. Add your API key

​3. Initialize

​4. Trace generateText

​5. Trace streamText

​Expected trace output

​Troubleshooting

​Next steps

Debugging Vercel AI SDK

Multi-step agents

Time-travel debugging

Cost tracking

Prerequisites

1. Install

2. Add your API key

3. Initialize

4. Trace `generateText`

5. Trace `streamText`

Expected trace output

Troubleshooting

Next steps