LlamaIndex

Tracing

Pick the tracing path that fits your application. Auto-instrumentation is the recommended path for most users.

Auto-instrumentation
OpenTelemetry

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.

Install dependencies

pip install braintrust llama-index llama-index-llms-openai

Set environment variables

.env

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.

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:

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, recorded as <ExceptionType>: <message>

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.

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.

Install dependencies

pip install "braintrust[otel]" llama-index-llms-openai openinference-instrumentation-llama-index python-dotenv

Set environment variables

.env

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.

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

AI providers

SDKs

Developer tools

Tracing

Setup

Trace your application

What Braintrust traces

Setup

Trace your application

What Braintrust traces

Resources

​Tracing

​Setup

​Trace your application

​What Braintrust traces

​Setup

​Trace your application

​What Braintrust traces

​Resources

Tracing

Setup

Trace your application

What Braintrust traces

Setup

Trace your application

What Braintrust traces

Resources