Tracing Pick the tracing path that fits your application. Auto-instrumentation is the recommended path for most users. 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: * LLM call spans (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) * 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 `: ` 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. 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](/integrations/sdk-integrations/opentelemetry) * [Trace LLM calls](/instrument/trace-llm-calls)