Gentrace Documentation

The init() function initializes the Gentrace SDK with your API credentials and configuration options. This function must be called early in your application setup to configure the SDK globally before using any other Gentrace functionality. Starting with the latest SDK versions, init() also automatically configures OpenTelemetry by default, eliminating the need for manual OpenTelemetry setup in most cases.

Basic usage

init.ts

import { init } from 'gentrace';

// Basic initialization with API key
init({
  apiKey: 'your-gentrace-api-key',
});

// Or using environment variable
init({
  apiKey: process.env.GENTRACE_API_KEY,
});

Getting an API Key: You can generate an API key by visiting https://gentrace.ai/s/api-keys

Overview

The init() function:

Configures authentication with your Gentrace API key
Sets up global client instances for making API requests
Establishes connection settings like base URL, timeouts, and retry behavior
Enables SDK functionality by making other Gentrace functions available
Automatically configures OpenTelemetry (by default) with proper exporters and settings

Parameters

Stainless SDK Generation: The parameters and client options described in this section are automatically generated by the Stainless API SDK generation platform.

Function signatures

interface InitOptions extends ClientOptions {
  otelSetup?: boolean | SetupConfig;
}

function init(options: InitOptions = {}): void;

Parameters

options

ClientOptions

default:"{}"

Configuration options for initializing the Gentrace SDK client.

Hide ClientOptions

apiKey

string

Your Gentrace API key. If not provided, the SDK will attempt to use the GENTRACE_API_KEY environment variable.Generate an API key at https://gentrace.ai/s/api-keys

baseURL

string | null

Override the default base URL for the API.Defaults to GENTRACE_BASE_URL environment variable or https://gentrace.ai/api.This is particularly useful for self-hosted Gentrace instances (e.g., http://self-hosted-gentrace.example.com/api)

timeout

number

Maximum time in milliseconds to wait for a response from the server before timing out a single request.

maxRetries

number

default:"2"

Maximum number of times to retry a request in case of temporary failure.

defaultHeaders

HeadersLike

Default headers to include with every request to the API.Example:

{
  'X-Custom-Header': 'your-value',
  'User-Agent': 'MyApp/1.0.0'
}

defaultQuery

Record<string, string | undefined>

Default query parameters to include with every request to the API.

logLevel

'debug' | 'info' | 'warn' | 'error'

Set the log level for SDK operations.Defaults to GENTRACE_LOG environment variable or 'warn'

logger

Logger

Custom logger instance for SDK logging.Defaults to globalThis.console

fetchOptions

RequestInit

Additional options to be passed to underlying fetch calls.

fetch

Fetch

Custom fetch function implementation for making HTTP requests.

otelSetup

boolean | SetupConfig

default:"true"

OpenTelemetry setup configuration. Controls automatic OpenTelemetry configuration.

true (default): Automatically configures OpenTelemetry with default settings
false: Disables automatic OpenTelemetry configuration
SetupConfig: Custom configuration object for OpenTelemetry

Hide SetupConfig

serviceName

string

The service name for your application. If not provided, attempts to auto-detect from package.json.

sampler

Sampler

Custom sampler instance. Defaults to new GentraceSampler() which samples traces with gentrace.sample=true in baggage. Gentrace wrapper functions add this flag automatically.

resourceAttributes

Record<string, string | number>

Additional resource attributes to include with all spans.Example:

{
  'service.version': '1.0.0',
  'deployment.environment': 'production'
}

instrumentations

Instrumentation[]

Array of OpenTelemetry instrumentations to enable. Useful for auto-instrumenting libraries.

traceEndpoint

string

Custom OTLP endpoint URL. Defaults to Gentrace’s OTLP endpoint.Example: http://localhost:4318/v1/traces

spanProcessors

SpanProcessor[]

Additional span processors to add to the tracer provider.

contextManager

ContextManager

Custom context manager. Defaults to AsyncLocalStorageContextManager.

propagator

TextMapPropagator

Custom propagator for context propagation. Defaults to W3C Trace Context propagator.

Advanced configuration

Automatic OpenTelemetry setup (default)

auto-otel.ts

import { init } from 'gentrace';

// OpenTelemetry is automatically configured by default
init({
  apiKey: process.env.GENTRACE_API_KEY,
});

// Same as explicitly setting otelSetup: true
init({
  apiKey: process.env.GENTRACE_API_KEY,
  otelSetup: true,
});

Custom OpenTelemetry configuration

custom-otel.ts

import { init, GentraceSampler } from 'gentrace';

init({
  apiKey: process.env.GENTRACE_API_KEY,
  otelSetup: {
    serviceName: 'my-ai-service',
    sampler: new GentraceSampler(),
    resourceAttributes: {
      'service.version': '1.0.0',
      'deployment.environment': 'production',
      'team': 'ai-platform',
    },
    // Add custom instrumentations if needed
    instrumentations: [],
  },
});

Custom OTEL collector endpoint

If you’re using your own OpenTelemetry collector, configure the trace exporter in the otelSetup configuration:

custom-collector.ts

import { init, GentraceSampler, interaction } from 'gentrace';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

init({
  apiKey: process.env.GENTRACE_API_KEY,
  otelSetup: {
    serviceName: 'my-ai-service',
    sampler: new GentraceSampler(),
    
    // Configure your custom OTEL collector endpoint
    traceEndpoint: 'http://localhost:4318/v1/traces',
    
    resourceAttributes: {
      'service.version': '1.0.0',
      'deployment.environment': 'production',
    },
  },
});

// Your instrumented functions will now send traces to your collector
const generateResponse = interaction(
  'generate-response',
  async (prompt: string) => {
    const result = await generateText({
      model: openai('gpt-4o'),
      prompt,
      experimental_telemetry: {
        isEnabled: true,
      },
    });
    return result.text;
  },
  {
    pipelineId: process.env.GENTRACE_PIPELINE_ID!,
  },
);

Common OTEL Collector configurations:

Local development: http://localhost:4318/v1/traces
Docker: http://otel-collector:4318/v1/traces
Kubernetes: http://otel-collector.observability.svc.cluster.local:4318/v1/traces
Cloud providers: Check your provider’s documentation for the correct endpoint

Disable automatic OpenTelemetry setup

manual-otel.ts

import { init } from 'gentrace';

// Disable automatic OpenTelemetry configuration
init({
  apiKey: process.env.GENTRACE_API_KEY,
  otelSetup: false,
});

// You must configure OpenTelemetry manually
// See the OpenTelemetry Setup guide for details

Custom base URL and timeout

custom-config.ts

import { init } from 'gentrace';

init({
  apiKey: process.env.GENTRACE_API_KEY,
  baseURL: 'https://your-custom-domain.com/api',
  timeout: 30000, // 30 seconds
  maxRetries: 5,
});

Custom headers and logging

headers-logging.ts

import { init } from 'gentrace';

init({
  apiKey: process.env.GENTRACE_API_KEY,
  defaultHeaders: {
    'X-Custom-Header': 'your-value',
    'User-Agent': 'MyApp/1.0.0',
  },
  logLevel: 'debug',
  logger: console, // or your custom logger
});

Environment variables

Instead of passing configuration options directly to init(), you can use environment variables:

GENTRACE_API_KEY: Your Gentrace API key
GENTRACE_BASE_URL: Custom base URL for the API (useful for self-hosted instances)
GENTRACE_LOG (TypeScript only): Log level setting

.env

# Set environment variables
export GENTRACE_API_KEY="your-gentrace-api-key"
export GENTRACE_BASE_URL="https://your-custom-domain.com/api"

env-init.ts

import { init } from 'gentrace';

// Initialize without parameters - uses environment variables
init();

Error handling

The init() function will throw an error if required configuration is missing:

error-handling.ts

import { init } from 'gentrace';

try {
  init({
    // Missing apiKey - will throw error if GENTRACE_API_KEY env var not set
  });
} catch (error) {
  console.error('Failed to initialize Gentrace:', error.message);
}

Automatic OpenTelemetry Setup: Starting with the latest SDK versions, init() automatically configures OpenTelemetry by default. This eliminates the need for manual OpenTelemetry setup in most cases. If you need custom OpenTelemetry configuration or want to disable automatic setup, use the otelSetup (TypeScript) or otel_setup (Python) parameter.

Best practices

1. Initialize early

Call init() before your main execution logic to ensure Gentrace is configured before using any tracing functionality:

early-init.ts

import { init, experiment, evalOnce } from 'gentrace';

// Initialize before using Gentrace functionality
init({
  apiKey: process.env.GENTRACE_API_KEY,
});

// Now you can use Gentrace functions
async function main() {
  await experiment('pipeline-id', async () => {
    // Your experiment code
  });
}

main();

2. Use environment variables

Store sensitive configuration like API keys in environment variables rather than hardcoding them:

# .env file
GENTRACE_API_KEY=your-gentrace-api-key
GENTRACE_BASE_URL=https://gentrace.ai/api

Requirements

API Key: A valid Gentrace API key is required. You can generate one at https://gentrace.ai/s/api-keys
Network Access: The SDK needs to communicate with the Gentrace API
Environment: Node.js 20+ (TypeScript) or Python 3.8+ (Python)

traced() - Lower-level function tracing
interaction() - Instrument AI functions for tracing
experiment() - Create testing contexts for grouping evaluations
evalDataset() / eval_dataset() - Run tests against datasets
eval() / evalOnce() - Run individual test cases

Getting started

Error analysis

Tracing

Evaluation

Integrations

Administration

Reference

SDK Entities

Initialization

Basic usage

Overview

Parameters

Function signatures

Parameters

Advanced configuration

Automatic OpenTelemetry setup (default)

Custom OpenTelemetry configuration

Custom OTEL collector endpoint

Disable automatic OpenTelemetry setup

Custom base URL and timeout

Custom headers and logging

Environment variables

Error handling

Best practices

1. Initialize early

2. Use environment variables

Requirements

Getting started

Error analysis

Tracing

Evaluation

Integrations

Administration

Reference

SDK Entities

​Basic usage

​Overview

​Parameters

​Function signatures

​Parameters

​Advanced configuration

​Automatic OpenTelemetry setup (default)

​Custom OpenTelemetry configuration

​Custom OTEL collector endpoint

​Disable automatic OpenTelemetry setup

​Custom base URL and timeout

​Custom headers and logging

​Environment variables

​Error handling

​Best practices

​1. Initialize early

​2. Use environment variables

​Requirements

​Related functions

Basic usage

Overview

Parameters

Function signatures

Parameters

Advanced configuration

Automatic OpenTelemetry setup (default)

Custom OpenTelemetry configuration

Custom OTEL collector endpoint

Disable automatic OpenTelemetry setup

Custom base URL and timeout

Custom headers and logging

Environment variables

Error handling

Best practices

1. Initialize early

2. Use environment variables

Requirements

Related functions