API Reference

Complete reference for @uselumina/sdk.

initLumina(config)

Initialize the Lumina client. Parameters:

Parameter	Type	Required	Description
`config.endpoint`	string	Yes	OTLP endpoint URL
`config.service_name`	string	Yes	Service identifier
`config.enabled`	boolean	No	Enable tracing (default: true)
`config.resource`	object	No	Resource attributes

Returns: Lumina instance Example:

const lumina = initLumina({
  endpoint: 'http://localhost:9411/v1/traces',
  service_name: 'my-service',
});

lumina.traceLLM(fn, options)

Trace an LLM call with automatic attribute extraction. Parameters:

Parameter	Type	Required	Description
`fn`	`() => Promise<T>`	Yes	Async function returning LLM response
`options.name`	string	No	Span name
`options.system`	string	No	Provider (openai, anthropic)
`options.prompt`	string	No	Input prompt
`options.metadata`	object	No	Custom attributes

Returns: Promise<T> Example:

await lumina.traceLLM(
  () => openai.chat.completions.create({ model: 'gpt-4', messages }),
  { name: 'chat', system: 'openai', prompt: userMessage }
);

lumina.trace(name, fn)

Create a parent span for hierarchical tracing. Parameters:

Parameter	Type	Required	Description
`name`	string	Yes	Span name
`fn`	`(span: Span) => Promise<T>`	Yes	Async function to trace

Returns: Promise<T> Example:

await lumina.trace('rag_pipeline', async (span) => {
  span.setAttribute('query', query);
  // Your code here
});

lumina.flush()

Flush all buffered spans immediately. Returns: Promise<void>

lumina.shutdown()

Flush and shut down the SDK. Returns: Promise<void>

Span API

span.setAttribute(key, value) Add attribute to span.

span.setAttribute('userId', 'user-123');
span.setAttribute('cost', 0.003);

span.addEvent(name, attributes?) Add event to span.

span.addEvent('processing_started');
span.addEvent('checkpoint', { progress: 50 });

span.setStatus(status) Set span status.

span.setStatus({ code: 'OK' });
span.setStatus({ code: 'ERROR', message: 'Failed to process' });

TypeScript/JavaScript

Python

Other Languages

initLumina(config)

lumina.traceLLM(fn, options)

lumina.trace(name, fn)

lumina.flush()

lumina.shutdown()

Span API

​initLumina(config)

​lumina.traceLLM(fn, options)

​lumina.trace(name, fn)

​lumina.flush()

​lumina.shutdown()

​Span API

initLumina(config)

lumina.traceLLM(fn, options)

lumina.trace(name, fn)

lumina.flush()

lumina.shutdown()

Span API