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
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) |
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)
- 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.
