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

# Tracing

> Background span submission, flush(), and error handling

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

```typescript theme={null}
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:

```typescript theme={null}
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:

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

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

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

## Waiting for Spans

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

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
// 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)

<Note>
  Spans are stored securely and retained according to your plan's data retention policy.
</Note>