> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# LlamaIndex

> Trace LlamaIndex calls in Braintrust to debug prompts, evaluate models, and monitor RAG pipelines

[LlamaIndex](https://docs.llamaindex.ai/) is a data framework for building LLM-powered applications over external data. Braintrust traces LlamaIndex LLM calls, embeddings, query engines, and agent and workflow runs.

**Python**

Braintrust offers two ways to trace LlamaIndex: auto-instrumentation, the recommended path for most users, and an OpenTelemetry pipeline.

## Auto-instrumentation

To trace LlamaIndex calls without modifying your application code, call `auto_instrument()` at startup. This also enables Braintrust's instrumentation for any other supported AI libraries your app uses (OpenAI, Anthropic, LiteLLM, etc.).

### Setup

Install the Braintrust SDK and LlamaIndex, then configure your environment.

**1. Install dependencies**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pip install braintrust llama-index llama-index-llms-openai
```

**2. Set environment variables**

```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY=your-api-key
OPENAI_API_KEY=your-openai-key

# For organizations on the EU data plane, use https://api-eu.braintrust.dev
# For self-hosted deployments, use your data plane URL
# BRAINTRUST_API_URL=<your-braintrust-api-url>
```

### Trace your application

Call `auto_instrument()` once at startup; every LLM, embedding, and query engine call is traced automatically.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import braintrust

braintrust.auto_instrument()
braintrust.init_logger(project="my-project")

from llama_index.llms.openai import OpenAI

llm = OpenAI(model="gpt-4o-mini")
response = llm.complete("What is the capital of Australia?")
print(str(response))
```

If you only want LlamaIndex traced (not OpenAI, Anthropic, or other supported libraries), call `setup_llamaindex()` instead. It enables the same dispatcher-based tracing but doesn't touch other integrations:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from braintrust.integrations.llamaindex import setup_llamaindex

setup_llamaindex(project_name="my-project")

from llama_index.llms.openai import OpenAI

llm = OpenAI(model="gpt-4o-mini")
response = llm.complete("What is the capital of Australia?")
print(str(response))
```

### What Braintrust traces

Braintrust captures:

* Task spans for LLM calls (e.g., `OpenAI`, `Anthropic`), with prompt or message list input, response output (role and content for chat, text for completion), and metadata (class, model, temperature, max\_tokens, provider)
* Embedding spans (e.g., `OpenAIEmbedding`), with input text
* Query engine spans (e.g., `RetrieverQueryEngine`), with query input, response text, and source nodes (score, text, node ID, metadata)
* Node parser spans (e.g., `SentenceSplitter`), with input documents
* Agent, workflow, and tool spans
* Errors on any span

> [!NOTE]
>
> Token usage and streaming response output are not captured on LlamaIndex spans. LlamaIndex is an orchestration layer; token counts appear on the underlying provider span (e.g., OpenAI) to avoid double-counting, and streaming chunks are captured downstream by the provider integration. For the same reason, LlamaIndex LLM calls are typed as task spans rather than LLM spans, so the underlying provider integration owns the LLM span and duplicate span nesting is avoided.

## OpenTelemetry

To trace LlamaIndex calls via OpenTelemetry, attach Braintrust's span processor to an OTel tracer provider and instrument LlamaIndex with the OpenInference instrumentor. This path is useful when you already have an OpenTelemetry pipeline or want to send the same traces to multiple backends.

### Setup

Install LlamaIndex along with the Braintrust OTel extras and the OpenInference LlamaIndex instrumentor, then configure your environment. `BRAINTRUST_PARENT` associates OTel traces with a Braintrust project.

**1. Install dependencies**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pip install "braintrust[otel]" llama-index-llms-openai openinference-instrumentation-llama-index python-dotenv
```

**2. Set environment variables**

```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY=your-api-key
BRAINTRUST_PARENT=project_name:my-project
OPENAI_API_KEY=your-openai-key

# For organizations on the EU data plane, use https://api-eu.braintrust.dev
# For self-hosted deployments, use your data plane URL
# BRAINTRUST_API_URL=<your-braintrust-api-url>
```

### Trace your application

Attach `BraintrustSpanProcessor` to an OTel `TracerProvider`, then instrument LlamaIndex with `LlamaIndexInstrumentor` from the OpenInference package.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from braintrust.otel import BraintrustSpanProcessor
from dotenv import load_dotenv
from llama_index.core.llms import ChatMessage
from llama_index.llms.openai import OpenAI
from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider

load_dotenv()

# Configure OpenTelemetry to send LlamaIndex traces to Braintrust.
# BraintrustSpanProcessor reads BRAINTRUST_API_KEY and BRAINTRUST_PARENT
# from the environment to authenticate and route traces.
provider = TracerProvider()
trace.set_tracer_provider(provider)
provider.add_span_processor(BraintrustSpanProcessor())
LlamaIndexInstrumentor().instrument(tracer_provider=provider)

# Your LlamaIndex application code
messages = [
    ChatMessage(role="system", content="Speak like a pirate. ARRR!"),
    ChatMessage(role="user", content="What do llamas sound like?"),
]
result = OpenAI().chat(messages)
print(result)
```

The spans appear in your Braintrust project. `BraintrustSpanProcessor` uses the environment variables from setup to authenticate and route them.

### What Braintrust traces

On Braintrust-hosted deployments, `LlamaIndexInstrumentor` spans use the [OpenInference mappings](https://docs.braintrust.dev/integrations/sdk-integrations/opentelemetry/attributes.md#openinference-attributes):

* LLM spans capture messages, tool calls, images, model parameters, tools, and token usage, including cached and reasoning tokens. Messages with media that cannot fit the chat format retain their OpenInference structure.
* Chain, tool, and agent spans use `input.value` and `output.value` for their inputs and outputs.
* Retrieval spans capture retrieved documents as `output`. Embedding spans capture embedded text as `input`.
* Span types come from `openinference.span.kind`.
* Errors are captured from OTel exception events.

Unmapped attributes, such as `session.id`, remain in `metadata`. See [attribute preservation settings](https://docs.braintrust.dev/integrations/sdk-integrations/opentelemetry/attributes.md#why-are-some-attributes-missing-from-metadata) for how mapped attributes are stored.

## Resources

* [LlamaIndex example](https://github.com/braintrustdata/braintrust-sdk-python/tree/main/examples/llamaindex)
* [LlamaIndex documentation](https://docs.llamaindex.ai/)
* [Braintrust OpenTelemetry guide](https://docs.braintrust.dev/integrations/sdk-integrations/opentelemetry/send-traces-and-logs.md)
* [Trace LLM calls](https://docs.braintrust.dev/instrument/trace-llm-calls.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.