The interaction() function wraps your AI functions with OpenTelemetry tracing to track interactions within a Gentrace pipeline. It creates spans for function execution, records arguments and outputs, and automatically manages OpenTelemetry baggage to ensure proper sampling and tracing context.
The Gentrace SDK automatically configures OpenTelemetry when you call init(). If you have an existing OpenTelemetry setup or need custom configuration, see the manual setup guide.

​
Basic usage

import { init, interaction } from 'gentrace';
import { Anthropic } from '@anthropic-ai/sdk';

init({
  apiKey: process.env.GENTRACE_API_KEY,
});

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

async function queryAI(prompt: string): Promise<string> {
  const response = await anthropic.messages.create({
    model: 'claude-opus-4-20250514',
    messages: [{ role: 'user', content: prompt }],
    max_tokens: 1024,
  });
  return response.content[0].text;
}

const tracedQueryAI = interaction('Query AI', queryAI);

// Use the traced function
const result = await tracedQueryAI('What is the capital of France?');
console.log(result);
The Gentrace SDK automatically configures the GentraceSpanProcessor when you call init(), which simplifies the process of converting baggage values to span attributes, ensuring proper trace routing to Gentrace. For manual configuration details, see the OpenTelemetry setup guide.
The GentraceSpanProcessor simplifies baggage-to-span attribute conversion by automatically copying baggage values (like gentrace.sample=true) to span attributes. This ensures that the OpenTelemetry Collector can properly identify and route Gentrace-related traces without requiring manual attribute management in your code.

​
Overview

An interaction in Gentrace represents a single AI function call or operation within your pipeline. The interaction() function:
  1. Creates OpenTelemetry spans for function execution with detailed tracing
  2. Records function arguments and outputs as span events for debugging
  3. Manages OpenTelemetry baggage by setting gentrace.sample="true" for proper sampling
  4. Associates with pipelines by adding the gentrace.pipeline_id attribute
  5. Handles errors gracefully by recording exceptions and setting span status

​
Parameters

/**
 * Wrap a function with Gentrace interaction tracing
 *
 * @param name - The name for the OpenTelemetry span
 * @param fn - The function to wrap with tracing
 * @param options - Configuration options
 * @param options.pipelineId - The UUID of the Gentrace pipeline
 *                             this interaction belongs to
 * @param options.attributes - Additional attributes to set
 *                             on the span
 *
 * @returns The wrapped function with the same signature
 *          but enhanced with tracing capabilities
 */
function interaction<F extends (...args: any[]) => any>(
  name: string,
  fn: F,
  options: {
    pipelineId: string;
    attributes?: Record<string, any>;
  },
): F;

​
Additional attributes

You can add custom attributes to the OpenTelemetry span using the attributes option. 
import { interaction } from 'gentrace';
import { OpenAI } from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

async function generateText(prompt: string): Promise<string> {
  const response = await openai.chat.completions.create({
    model: 'o3',
    messages: [{ role: 'user', content: prompt }],
  });
  return response.choices[0].message.content || '';
}

const tracedGenerateText = interaction(
  'Generate Text',
  generateText,
  {
    attributes: {
      provider: 'openai',
      version: '1.0.0',
    },
  },
);

const result = await tracedGenerateText(
  'Write a haiku about coding',
  0.7,
);

​
OpenTelemetry integration

The interaction() function provides deep integration with OpenTelemetry:

​
Span creation and attributes

  • Span Name: Uses the provided name parameter
  • Pipeline ID: Automatically adds gentrace.pipeline_id attribute
  • Custom Attributes: Merges any additional attributes you provide
  • Function Metadata: Records function name and execution context

​
Baggage management

The function automatically manages OpenTelemetry baggage: 
// Automatically sets baggage for the duration of the function
import { context, propagation } from '@opentelemetry/api';

const currentContext = context.active();
const currentBaggage =
  propagation.getBaggage(currentContext) ??
  propagation.createBaggage();

const newBaggage = currentBaggage.setEntry('gentrace.sample', {
  value: 'true',
});
const newContext = propagation.setBaggage(currentContext, newBaggage);
This ensures that:
  • All nested spans are properly sampled
  • Gentrace can identify and process the traces
  • Context is preserved across async boundaries

​
Event recording

Function arguments and outputs are recorded as span events:
  • Arguments Event: gentrace.fn.args with serialized function arguments
  • Output Event: gentrace.fn.output with serialized return value
  • Exception Events: Automatic exception recording with stack traces

​
Error handling

The interaction() function handles errors gracefully and automatically associates all errors and exceptions with the OpenTelemetry span: 
import { interaction } from 'gentrace';

async function riskyAIFunction(input: string): Promise<string> {
  if (input.length === 0) {
    throw new Error('Input cannot be empty');
  }
  // AI processing logic
  return `Processed: ${input}`;
}

const tracedRiskyFunction = interaction(
  'Risky AI Function',
  riskyAIFunction,
);

try {
  const result = await tracedRiskyFunction('');
} catch (error) {
  // Error is automatically recorded in the OpenTelemetry span with:
  // - Exception event with stack trace
  // - Span status set to ERROR
  // - Error type and message as attributes
}

​
OTEL span error integration

When errors occur within interactions:
  • Automatic Capture: All Error objects (TypeScript) and exceptions (Python) are automatically captured as span events
  • Stack Traces: Full stack traces are preserved in the span for debugging
  • Error Attributes: Error messages, types, and metadata are recorded as span attributes
  • Span Status: The span status is automatically set to ERROR when unhandled exceptions occur

​
Usage in experiments

The interaction() function works seamlessly with Gentrace experiments: 
import { experiment, evalOnce, interaction } from 'gentrace';
import { OpenAI } from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// Define your AI function
async function summarizeText(text: string): Promise<string> {
  // Your summarization logic
  const response = await openai.chat.completions.create({
    model: 'o3',
    messages: [
      {
        role: 'system',
        content: 'Summarize the following text concisely.',
      },
      { role: 'user', content: text },
    ],
  });
  return response.choices[0].message.content || '';
}

// Wrap with interaction tracing
const tracedSummarizeText = interaction(
  'Summarize Text',
  summarizeText,
  {
    attributes: {
      model: 'o3',
      task: 'summarization',
    },
  },
);

// Use in experiments
experiment(async () => {
  await evalOnce('summarization-test', async () => {
    const longText =
      'This is a very long article about artificial intelligence...';
    const summary = await tracedSummarizeText(longText);

    // Evaluate the summary quality
    return {
      summary,
      length: summary.length,
      quality_score: calculateQualityScore(summary),
    };
  });
});

​
Requirements

​
Gentrace SDK Initialization
configuration
required
Must call init() with a valid API key. The SDK automatically configures OpenTelemetry for you. For custom OpenTelemetry setups, see the manual setup guide.
​
Valid Pipeline ID
UUID
When provided, must be a valid UUID for an existing Gentrace pipeline. If omitted, uses the default pipeline
​
Function Compatibility
function
Works with both synchronous and asynchronous functions