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,
});

from gentrace import init

# Basic initialization with API key
init(api_key="your-gentrace-api-key")

# Or using environment variable
import os
from gentrace import init

init(api_key=os.environ["GENTRACE_API_KEY"])

Getting an API Key: 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;

def init(
    *,
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    otel_setup: Union[bool, Dict[str, Any]] = True,
    **kwargs: Any
) -> None

Parameters

TypeScript
Python

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.When running experiments, the SDK also adds gentrace.in_experiment=true to the baggage to mark test spans, preventing production evaluations from running on test data.

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.

api_key

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

base_url

string

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)

otel_setup

bool | dict

default:"True"

OpenTelemetry setup configuration. Controls automatic OpenTelemetry configuration.

True (default): Automatically configures OpenTelemetry with default settings
False: Disables automatic OpenTelemetry configuration
dict: Custom configuration dictionary for OpenTelemetry

Hide Configuration options

service_name

str

The service name for your application. If not provided, attempts to auto-detect from pyproject.toml or setup.py.

sampler

Sampler

Custom sampler instance. Defaults to GentraceSampler() which samples traces with gentrace.sample=true in baggage. Gentrace wrapper functions add this flag automatically.When running experiments, the SDK also adds gentrace.in_experiment=true to the baggage to mark test spans, preventing production evaluations from running on test data.

resource_attributes

Dict[str, Union[str, int, float, bool]]

Additional resource attributes to include with all spans.Example:

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

instrumentations

List[BaseInstrumentor]

List of OpenTelemetry instrumentation instances to enable. Useful for auto-instrumenting libraries like OpenAI, Anthropic, etc.Example:

from openinference.instrumentation.openai import OpenAIInstrumentor

instrumentations=[OpenAIInstrumentor()]

trace_endpoint

str

Custom OTLP endpoint URL. Defaults to Gentrace’s OTLP endpoint.

debug

bool

default:"False"

Enable console exporter for debugging. When True, spans are also printed to console.

**kwargs

Any

Additional keyword arguments passed to the underlying client constructors.

Show Additional options

timeout

float | Timeout

Maximum time to wait for a response from the server.Can be a float representing seconds or a more complex timeout configuration.

max_retries

int

default:"2"

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

default_headers

Mapping[str, str]

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

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

default_query

Mapping[str, object]

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

http_client

httpx.Client

Custom HTTP client instance for making requests.This allows for advanced customization of the underlying HTTP behavior.

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,
});

import gentrace
import os

# OpenTelemetry is automatically configured by default
gentrace.init(
    api_key=os.environ["GENTRACE_API_KEY"],
)

# Same as explicitly setting otel_setup=True
gentrace.init(
    api_key=os.environ["GENTRACE_API_KEY"],
    otel_setup=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: [],
  },
});

import gentrace
from gentrace import GentraceSampler
from openinference.instrumentation.openai import OpenAIInstrumentor
import os

gentrace.init(
    api_key=os.environ["GENTRACE_API_KEY"],
    otel_setup={
        "service_name": "my-ai-service",
        "sampler": GentraceSampler(),
        "resource_attributes": {
            "service.version": "1.0.0",
            "deployment.environment": "production",
            "team": "ai-platform",
        },
        # Add OpenAI instrumentation for automatic tracing
        "instrumentations": [OpenAIInstrumentor()],
        # Enable debug mode to see spans in console
        "debug": True,
    },
)

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!,
  },
);

import gentrace
from gentrace import GentraceSampler, interaction
from openai import AsyncOpenAI
import os

gentrace.init(
    api_key=os.environ["GENTRACE_API_KEY"],
    otel_setup={
        "service_name": "my-ai-service",
        "sampler": GentraceSampler(),

        # Configure your custom OTEL collector endpoint
        "trace_endpoint": "http://localhost:4318/v1/traces",

        "resource_attributes": {
            "service.version": "1.0.0",
            "deployment.environment": "production",
        },

        # Enable debug mode to see spans in console while testing
        "debug": True,
    },
)

# Your instrumented functions will now send traces to your collector
client = AsyncOpenAI()

@interaction(name="generate-response")
async def generate_response(prompt: str) -> str:
    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content

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

import gentrace
import os

# Disable automatic OpenTelemetry configuration
gentrace.init(
    api_key=os.environ["GENTRACE_API_KEY"],
    otel_setup=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,
});

from gentrace import init
import os

init(
    api_key=os.environ["GENTRACE_API_KEY"],
    base_url="https://your-custom-domain.com/api",
    timeout=30.0,  # 30 seconds
    max_retries=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
});

from gentrace import init
import os

init(
    api_key=os.environ["GENTRACE_API_KEY"],
    default_headers={
        "X-Custom-Header": "your-value",
        "User-Agent": "MyApp/1.0.0"
    }
)

Environment variables

Instead of passing configuration options directly to init(), consider using 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();

from gentrace import init

# 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);
}

from gentrace import init, GentraceError

try:
    init()
    # Missing api_key - will throw error if GENTRACE_API_KEY env var not set
except GentraceError as e:
    print(f"Failed to initialize Gentrace: {e}")

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(async () => {
    // Your experiment code
  });
}

main();

from gentrace import init, experiment, eval
import os

# Initialize before using Gentrace functionality
init(api_key=os.environ["GENTRACE_API_KEY"])

# Now you can use Gentrace functions
@experiment
async def main():
    # Your experiment code
    pass

if __name__ == "__main__":
    import asyncio
    asyncio.run(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. 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

​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