Skip to main content
This guide will help you set up the ZeroEval TypeScript SDK and make your first traced API call.

​
Prerequisites

  • Node.js 18 or higher
  • A ZeroEval API key (get one at zeroeval.com)
  • An OpenAI API key (for this example)

​
Installation

1

Install the SDK

Install the ZeroEval SDK using your preferred package manager:
npm install zeroeval
2

Install OpenAI SDK

For this quickstart, you’ll also need the OpenAI SDK:
npm install openai
3

Set up environment variables

Create a .env file in your project root with your API keys:
.env
ZEROEVAL_API_KEY=your_zeroeval_api_key
OPENAI_API_KEY=your_openai_api_key
The SDK auto-initializes on first span if ZEROEVAL_API_KEY is set in your environment.
4

Create your first traced application

Create a new file called app.ts and add the following code:
app.ts
import * as ze from "zeroeval";
import { OpenAI } from "openai";

// Initialize the ZeroEval SDK
ze.init();

// Wrap the OpenAI client for automatic tracing
const openai = ze.wrap(new OpenAI());

async function main() {
  // This call is automatically traced
  const completion = await openai.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Hello!" }],
  });

  console.log(completion.choices[0].message.content);
}

main().catch(console.error);
The ze.wrap() function automatically detects the client type and instruments all API calls for tracing.
5

Run your application

Execute your application:
node app.ts
You should see the AI response in your console, and the trace will automatically appear in your ZeroEval dashboard.

​
What’s next?

Manual tracing

Learn how to manually instrument your code

Integrations

Explore integrations with Vercel AI SDK and LangChain

Signals

Add custom metrics and signals to your traces

Prompts

Manage and version your prompts with ZeroEval

Integrations

Explore integrations with Vercel AI SDK and LangChain

Signals

Add custom metrics and signals to your traces

Prompts

Manage and version your prompts with ZeroEval

​
Advanced example with custom spans

Here’s a more advanced example showing how to use custom spans and tags: 
import * as ze from "zeroeval";
import { OpenAI } from "openai";

ze.init({
  apiKey: process.env.ZEROEVAL_API_KEY,
  collectCodeDetails: true,
  flushInterval: 2,
});

const openai = ze.wrap(new OpenAI());

async function processWithAI() {
  await ze.withSpan({ name: "process_with_ai" }, async () => {
    // Set tags for the trace
    const traceId = ze.getCurrentTrace();
    if (traceId) {
      ze.setTag(traceId, { feature: "ai_processing", user: "demo" });
    }

    // Multiple AI calls within the same span
    const response = await openai.chat.completions.create({
      model: "gpt-4o-mini",
      messages: [{ role: "user", content: "What is 2 + 2?" }],
    });

    console.log(response.choices[0].message.content);
  });

  // Force flush before exit
  ze.tracer.shutdown();
}

processWithAI().catch(console.error);
The withSpan() helper creates a new span context and ensures proper parent-child relationships between spans.

Build docs developers (and LLMs) love

Get started for freeTalk to us