Skip to main content
The ZeroEval TypeScript SDK provides tracing for Node.js applications through wrapper functions and integration callbacks.

​
Installation

npm install zeroeval

​
Basic Setup

import * as ze from 'zeroeval';

// Option 1: ZEROEVAL_API_KEY in your environment variable
ze.init();

// Option 2: Provide API key directly
ze.init({ apiKey: 'YOUR_API_KEY' });

// Option 3: With additional configuration
ze.init({
  apiKey: 'YOUR_API_KEY',
  apiUrl: 'https://api.zeroeval.com', // optional
  flushInterval: 10, // seconds
  maxSpans: 100,
});

​
Patterns

The SDK offers two ways to add tracing to your TypeScript/JavaScript code:

​
Function Wrapping

Use withSpan() to wrap function executions: 
import * as ze from 'zeroeval';

// Wrap synchronous functions
const fetchData = (userId: string) =>
  ze.withSpan({ name: 'fetch_data' }, () => ({
    userId,
    name: 'John Doe'
  }));

// Wrap async functions
const processData = async (data: { name: string }) =>
  ze.withSpan(
    {
      name: 'process_data',
      attributes: { version: '1.0' }
    },
    async () => {
      const result = await transform(data);
      return `Welcome, ${result.name}!`;
    }
  );

// Complex workflows with nested spans
async function complexWorkflow() {
  return ze.withSpan({ name: 'data_pipeline' }, async () => {
    const data = await ze.withSpan(
      { name: 'fetch_stage' },
      fetchExternalData
    );

    const processed = await ze.withSpan(
      { name: 'process_stage' },
      () => transformData(data)
    );

    const result = await ze.withSpan(
      { name: 'save_stage' },
      () => saveToDatabase(processed)
    );

    return result;
  });
}

​
Decorators

Use the @span decorator for class methods: 
import { span } from 'zeroeval';

class DataService {
  @span({
    name: 'fetch_user_data',
    tags: { service: 'user_api' }
  })
  async fetchUser(userId: string) {
    const response = await fetch(`/api/users/${userId}`);
    return response.json();
  }

  @span({
    name: 'process_order',
    attributes: { version: '2.0' }
  })
  processOrder(orderId: string, items: string[]) {
    return { orderId, processed: true };
  }
}
Decorators require TypeScript configuration: Enable experimentalDecorators in your tsconfig.json:
{
  "compilerOptions": {
    "experimentalDecorators": true
  }
}
When using runtime tools like tsx or ts-node, pass the --experimental-decorators flag.

​
Sessions

Sessions group related spans together for tracking workflows, user interactions, or multi-step processes.

​
Basic Session

import { v4 as uuidv4 } from 'uuid';
import * as ze from 'zeroeval';

const sessionId = uuidv4();

async function userJourney(userId: string) {
  return ze.withSpan(
    {
      name: 'user_journey',
      sessionId: sessionId,
      sessionName: 'User Onboarding'
    },
    async () => {
      // All nested spans inherit the session
      await ze.withSpan({ name: 'step_1' }, () => welcome(userId));
      await ze.withSpan({ name: 'step_2' }, () => setupProfile(userId));
      await ze.withSpan({ name: 'step_3' }, () => sendConfirmation(userId));
    }
  );
}

​
Multi-Step Pipeline

async function ragPipeline(query: string) {
  const sessionId = uuidv4();

  return ze.withSpan(
    { name: 'rag_pipeline', sessionId, sessionName: 'RAG Query' },
    async () => {
      const docs = await ze.withSpan(
        { name: 'retrieve' },
        () => vectorSearch(query)
      );

      const ranked = await ze.withSpan(
        { name: 'rerank' },
        () => rerankDocs(query, docs)
      );

      return ze.withSpan(
        { name: 'generate' },
        () => generateAnswer(query, ranked)
      );
    }
  );
}

​
Context

Access current context information: 
import * as ze from 'zeroeval';

// Get the current span
const currentSpan = ze.getCurrentSpan();

// Get the current trace ID
const traceId = ze.getCurrentTrace();

// Get the current session ID
const sessionId = ze.getCurrentSession();

​
Tagging

Attach tags for filtering and organization: 
import * as ze from 'zeroeval';

// Set tags on the current span
ze.setTag(undefined, { user_id: '12345', environment: 'production' });

// Set tags on a specific trace
const traceId = ze.getCurrentTrace();
if (traceId) {
  ze.setTag(traceId, { feature: 'checkout' });
}

// Set tags on a span object
const span = ze.getCurrentSpan();
if (span) {
  ze.setTag(span, { action: 'process_payment' });
}

​
Feedback

To attach human or programmatic feedback to completions, see Human Feedback and the Feedback SDK docs. For automated quality evaluations, see Judges.

​
Advanced Configuration

Fine-tune the SDK behavior: 
import * as ze from 'zeroeval';

ze.init({
  apiKey: 'YOUR_API_KEY',
  apiUrl: 'https://api.zeroeval.com',
  flushInterval: 5,           // Flush every 5 seconds
  maxSpans: 200,              // Buffer up to 200 spans
  collectCodeDetails: true,   // Capture source code context
  debug: false,               // Enable debug logging
  integrations: {
    openai: true,             // Enable OpenAI integration
    vercelAI: true,           // Enable Vercel AI SDK integration
  }
});
Need help? Check out our GitHub examples or reach out on Discord.