initialize()

Initialize the Respan telemetry client

Overview

The initialize() method sets up the tracing client and establishes connection to Respan. This must be called before using any tracing methods.

Signature

1async initialize(): Promise<void>

Basic Usage

1import { RespanTelemetry } from '@respan/tracing';
2
3const respanAi = new RespanTelemetry({
4 apiKey: process.env.RESPAN_API_KEY,
5 appName: 'my-app'
6});
7
8// Initialize before using any tracing methods
9await respanAi.initialize();
10
11// Now ready to use
12await respanAi.withWorkflow(
13 { name: 'my_workflow' },
14 async () => {
15 return 'ready';
16 }
17);

Constructor Options

1const respanAi = new RespanTelemetry({
2 apiKey: string; // Required: Your Respan API key
3 baseURL?: string; // Optional: API base URL (default: https://api.respan.ai)
4 appName?: string; // Optional: Application name for identification
5 instrumentModules?: { // Optional: Modules to auto-instrument
6 openAI?: typeof OpenAI;
7 anthropic?: typeof Anthropic;
8 };
9 disableBatch?: boolean; // Optional: Send spans immediately (default: false)
10 logLevel?: string; // Optional: 'debug' | 'info' | 'warn' | 'error' (default: 'warn')
11});

Complete Example

1import { RespanTelemetry } from '@respan/tracing';
2import OpenAI from 'openai';
3
4const respanAi = new RespanTelemetry({
5 apiKey: process.env.RESPAN_API_KEY,
6 baseURL: 'https://api.respan.ai',
7 appName: 'production-app',
8 instrumentModules: {
9 openAI: OpenAI, // Auto-instrument OpenAI
10 },
11 disableBatch: false,
12 logLevel: 'info'
13});
14
15// Initialize the client
16await respanAi.initialize();
17console.log('Respan Tracing initialized successfully');
18
19// Use tracing
20await respanAi.withWorkflow(
21 { name: 'user_request' },
22 async () => {
23 // Your code here
24 }
25);
26
27// Shutdown gracefully when done
28await respanAi.shutdown();

Environment Variables

You can also configure using environment variables:

.env
$RESPAN_API_KEY=your-api-key
$RESPAN_BASE_URL=https://api.respan.ai
1const respanAi = new RespanTelemetry({
2 apiKey: process.env.RESPAN_API_KEY,
3 baseURL: process.env.RESPAN_BASE_URL,
4 appName: 'my-app'
5});
6
7await respanAi.initialize();

Configuration Options

apiKey
stringRequired

Your Respan API key from the dashboard

baseURL
stringDefaults to https://api.respan.ai

Respan API base URL

appName
string

Application name for identifying traces in the dashboard

instrumentModules
object

Modules to automatically instrument:

  • openAI: OpenAI SDK class
  • anthropic: Anthropic SDK class
disableBatch
boolean

If true, sends spans immediately instead of batching them

logLevel
stringDefaults to warn

Logging verbosity: "debug", "info", "warn", "error"

Best Practices

  • Always call initialize() before using any tracing methods
  • Initialize once at application startup
  • Use environment variables for sensitive configuration
  • Call shutdown() before application exit to flush pending spans
  • Enable auto-instrumentation for supported SDKs