Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tracia.io/llms.txt

Use this file to discover all available pages before exploring further.

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

​
How Tracing Works

  1. runLocal() completes the LLM call
  2. Returns the result immediately
  3. Submits the span to Tracia in the background
  4. 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

FieldDescription
spanIdUnique identifier for the span
traceIdSession ID if part of multi-turn conversation
parentSpanIdParent span ID for chained conversations
modelModel used for the request
providerProvider (openai, anthropic, google, amazon_bedrock)
input.messagesMessages sent (with variables interpolated)
variablesOriginal variables passed
outputGenerated response
statusSUCCESS or ERROR
latencyMsRequest duration
inputTokensInput token count
outputTokensOutput token count
tagsUser-defined tags
userIdEnd user identifier
sessionIdSession 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.