Tracing

By default, runLocal() automatically sends spans to Tracia in the background. This gives you observability without blocking your application.

How Tracing Works

runLocal() completes the LLM call
Returns the result immediately
Submits the span to Tracia in the background
Retries failed span submissions automatically

const result = await tracia.runLocal({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }]
});

// Result available immediately
console.log(result.text);
console.log(result.spanId); // "sp_1234567890abcdef"

// Span is being sent in the background

Span Metadata

Add metadata to help filter and analyze spans:

const result = await tracia.runLocal({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
  tags: ['production', 'chat', 'v2'],
  userId: 'user_abc123',
  sessionId: 'session_xyz789'
});

Span Fields

Field	Description
`spanId`	Unique identifier for the span
`traceId`	Session ID if part of multi-turn conversation
`parentSpanId`	Parent span ID for chained conversations
`model`	Model used for the request
`provider`	Provider (openai, anthropic, google, amazon_bedrock)
`input.messages`	Messages sent (with variables interpolated)
`variables`	Original variables passed
`output`	Generated response
`status`	SUCCESS or ERROR
`latencyMs`	Request duration
`inputTokens`	Input token count
`outputTokens`	Output token count
`tags`	User-defined tags
`userId`	End user identifier
`sessionId`	Session identifier

Custom Span ID

Provide your own span ID for correlation with external systems:

const result = await tracia.runLocal({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
  spanId: 'sp_a1b2c3d4e5f67890'
});

console.log(result.spanId); // "sp_a1b2c3d4e5f67890"

Custom span IDs must match the format: sp_ followed by exactly 16 hexadecimal characters (e.g., sp_1234567890abcdef).

Waiting for Spans

Use flush() to wait for all pending spans before shutdown:

const tracia = new Tracia({ apiKey: process.env.TRACIA_API_KEY });

// Run multiple requests
await Promise.all([
  tracia.runLocal({ model: 'gpt-4o', messages: [{ role: 'user', content: 'Request 1' }] }),
  tracia.runLocal({ model: 'gpt-4o', messages: [{ role: 'user', content: 'Request 2' }] }),
  tracia.runLocal({ model: 'gpt-4o', messages: [{ role: 'user', content: 'Request 3' }] }),
]);

// Wait for all background spans to complete
await tracia.flush();
console.log('All spans submitted');

Graceful Shutdown

process.on('SIGTERM', async () => {
  console.log('Shutting down...');
  await tracia.flush();
  process.exit(0);
});

Error Handling

onSpanError Callback

Handle span submission failures without affecting your main application:

const tracia = new Tracia({
  apiKey: process.env.TRACIA_API_KEY,
  onSpanError: (error, spanId) => {
    console.error(`Span ${spanId} failed:`, error.message);
    // Log to monitoring system, send alert, etc.
  }
});

const result = await tracia.runLocal({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }]
});
// LLM response returned even if span fails

Retry Behavior

Span submissions are automatically retried:

Up to 2 retry attempts
Exponential backoff (500ms, 1000ms)
onSpanError called only after all retries fail

Disabling Tracing

Disable tracing for specific requests:

const result = await tracia.runLocal({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
  sendTrace: false
});

console.log(result.spanId); // "" (empty string)

Use cases for disabling tracing:

Development and testing
Sensitive data that shouldn’t be logged
High-volume, low-value requests
Reducing costs on non-critical paths

Viewing Spans

Access spans in the Tracia dashboard or via the SDK:

// Get a specific span
const span = await tracia.spans.get('sp_1234567890abcdef');
console.log(span);

// List recent spans
const { spans } = await tracia.spans.list({
  tags: ['production'],
  limit: 10
});

Span Storage

Spans include:

Full input messages (after variable interpolation)
Original variables (for filtering)
Complete output text
Token usage and latency
LLM configuration (temperature, maxOutputTokens, topP)

Spans are stored securely and retained according to your plan’s data retention policy.

Getting Started

Node.js SDK

Python SDK

How Tracing Works

Span Metadata

Span Fields

Custom Span ID

Waiting for Spans

Graceful Shutdown

Error Handling

onSpanError Callback

Retry Behavior

Disabling Tracing

Viewing Spans

Span Storage

​How Tracing Works

​Span Metadata

​Span Fields

​Custom Span ID

​Waiting for Spans

​Graceful Shutdown

​Error Handling

​onSpanError Callback

​Retry Behavior

​Disabling Tracing

​Viewing Spans

​Span Storage

How Tracing Works

Span Metadata

Span Fields

Custom Span ID

Waiting for Spans

Graceful Shutdown

Error Handling

onSpanError Callback

Retry Behavior

Disabling Tracing

Viewing Spans

Span Storage