Braintrust offers two ways to trace LlamaIndex: auto-instrumentation, the recommended path for most users, and an OpenTelemetry pipeline.If you only want LlamaIndex traced (not OpenAI, Anthropic, or other supported libraries), call The spans appear in your Braintrust project.
Auto-instrumentation
To trace LlamaIndex calls without modifying your application code, callauto_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
2
Set environment variables
.env
Trace your application
Callauto_instrument() once at startup; every LLM, embedding, and query engine call is traced automatically.setup_llamaindex() instead. It enables the same dispatcher-based tracing but doesn’t touch other integrations: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.1
Install dependencies
2
Set environment variables
.env
Trace your application
AttachBraintrustSpanProcessor to an OTel TracerProvider, then instrument LlamaIndex with LlamaIndexInstrumentor from the OpenInference package.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:- 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.valueandoutput.valuefor their inputs and outputs. - Retrieval spans capture retrieved documents as
output. Embedding spans capture embedded text asinput. - Span types come from
openinference.span.kind. - Errors are captured from OTel exception events.
session.id, remain in metadata. See attribute preservation settings for how mapped attributes are stored.