Integrations / Next.js

Trace Next.js AI routes and Server Actions

To trace a Next.js AI route with Tracify, wrap the handler's work with traceAgent, wrap the model with the Tracify middleware, and wrap your tools. Each request becomes one trace with its model calls and tool calls.

Read the guideStart free

Your code

Next.js

Tracify

One run.

  • 01One trace per request to your AI route
  • 02Streaming generations with time to first token
  • 03Tool calls with input and output
  • 04Errors thrown inside the handler

Setup

6 steps.

  1. 01

    Install

    The Tracify SDK plus the Vercel AI SDK and a provider.

    bash
    npm install tracify-sdk ai @ai-sdk/openai
  2. 02

    Add your key

    Put the key in .env.local for development and in your Vercel project settings for production.

    bash
    TRACIFY_API_KEY=tracify_sk_live_...
  3. 03

    Use the Node.js runtime

    The SDK needs Node.js to keep concurrent requests in separate traces, so set the route to the Node.js runtime. It will not run on the edge runtime.

    typescript
    export const runtime = "nodejs";
  4. 04

    Wrap the model and the handler

    tracifyMiddleware records every generateText and streamText call made with the wrapped model. traceAgent turns each request into one run.

    typescript
    // app/api/chat/route.ts
import { openai } from "@ai-sdk/openai";
import { streamText, wrapLanguageModel } from "ai";
import { traceAgent, tracifyMiddleware } from "tracify-sdk";

export const runtime = "nodejs";

const model = wrapLanguageModel({
  model: openai("gpt-4o-mini"),
  middleware: tracifyMiddleware(),
});

const handle = traceAgent(async (prompt: string) => {
  const result = streamText({ model, prompt });
  return result.toTextStreamResponse();
}, { name: "chat-route" });

export async function POST(request: Request) {
  const { prompt } = await request.json();
  return handle(prompt);
}
  5. 05

    Add tool calls

    traceTools wraps each tool's execute function, so every tool call is its own step with input, output and time.

    typescript
    import { tool } from "ai";
import { z } from "zod";
import { traceTools } from "tracify-sdk";

const tools = traceTools({
  getOrder: tool({
    description: "Look up an order",
    inputSchema: z.object({ id: z.string() }),
    execute: async ({ id }) => fetchOrder(id),
  }),
});
  6. 06

    Run it once and look

    Run your code one time, then open the Tracing page of your project. Your route shows up as a run with its steps in order, plus the tokens, time and any error for each call.

Good to know

Streaming and serverless

A streamed model call is recorded when its stream ends. Data is sent in the background, so on a serverless host the last spans of a request can be lost if the function is frozen right after it responds. Check the first runs in Tracing after you deploy.

Good to know

Server Actions

Wrap the function the Server Action calls with traceAgent the same way. Anything marked use server runs on Node.js.

Full details in the documentation. All integrations are listed on the integrations page.

Does it work on the edge runtime?
No. The SDK uses Node.js async context, so set the route to the Node.js runtime.
Do I need the Vercel AI SDK?
No. You can use traceAgent with any model client, and wrap OpenAI or Anthropic clients directly. The AI SDK middleware is the shortest route when you already use it.
Does it work with the App Router and Server Actions?
Yes. Both run on Node.js, so wrap the function they call with traceAgent.
Will it slow down my route?
The TypeScript SDK sends data in the background and does not wait for Tracify. If Tracify cannot be reached, it logs a warning and your route keeps running.

Send your first trace.

Free to start.

Start freeCompare tools