> ## Documentation Index > Fetch the complete documentation index at: https://braintrust.dev/docs/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 If you are a coding agent, prefer the Braintrust [`bt` CLI](/docs/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE. [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. 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. ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} pip install braintrust llama-index llama-index-llms-openai ``` ```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= ```

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 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. ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} pip install "braintrust[otel]" llama-index-llms-openai openinference-instrumentation-llama-index python-dotenv ``` ```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= ```

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) ``` `LlamaIndexInstrumentor` emits OpenInference-conventioned spans for every LlamaIndex operation. `BraintrustSpanProcessor` handles auth and routing, so the standard Braintrust environment variables (`BRAINTRUST_API_KEY`, `BRAINTRUST_PARENT`, optionally `BRAINTRUST_API_URL`) are all you need.

What Braintrust traces

`LlamaIndexInstrumentor` emits OpenTelemetry spans for each instrumented LlamaIndex operation, following [OpenInference semantic conventions](https://arize-ai.github.io/openinference/spec/semantic_conventions.html). Braintrust receives them via OTLP and maps them onto its trace model: * LLM call spans get structured `input`, `output`, and token metrics * Embedding, retrieval, tool, and chain spans preserve their OpenInference attributes as raw fields in `metadata` * Errors are captured from OTel exception events

Resources

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