How do I trace LlamaIndex in Python?

Rius traces LlamaIndex in Python when you install the llama-index extra and call rius.init() once. Every query then shows up as a nested trace of retrieval, embedding and model-call spans, with tokens and cost on the model calls. The integration is Python only, and you do not change your index or query engine code.

How it works

The glassflow-rius[llama-index] extra installs the LlamaIndex instrumentation. With a default global rius.init(), Rius turns on every integration it finds installed, so there is no switch to flip for LlamaIndex. The Integrations page lists every library and framework handled this way.

• The extra installs the instrumentation, not llama-index itself. A project that already uses LlamaIndex has the package, and pip leaves it untouched.
• If the extra is installed without llama-index, init() logs a DependencyConflict and the integration stays off.
• If you also install the openai extra, the chat or completion call behind an LLM (streamed or not) appears as a second LLM span under the LlamaIndex span. Since glassflow-rius 1.1.1 Rius counts that call once in tokens and cost, and the LlamaIndex span still shows the call’s total.
• Calls from MultiModalLLM models, embedding models and retrievers are not nested this way. Their OpenAI span starts a trace of its own.
• On versions before 1.1.1, or on instrumentation versions outside the supported range, LLM calls are counted twice.

There is no LlamaIndex integration in TypeScript, so LlamaIndex.TS query-engine and retriever structure is not captured.

Set it up

1. Install the SDK with the LlamaIndex extra. The package name llama-index is included for a fresh environment. The SDK needs Python 3.10 or newer.

   pip install "glassflow-rius[llama-index]" llama-index

2. Call rius.init() once, as early as possible, before you build indexes and query engines. Use your own API key and a service_name that identifies your agent. The installation page covers every argument and environment variable.

   import rius
    
   rius.init(api_key="ri_...", service_name="my-agent")
   # build indexes and query engines exactly as before

3. Run one query against an index, exactly as you do today. There is no wrapper to add around the call.

4. Open the trace in the Rius console. The pipeline appears as nested spans, and the LLM leaf carries the model, tokens and cost.

For the full setup guide for this integration, see the LlamaIndex integration page.

What you get

Each query becomes a nested trace of typed spans:

• Retriever spans for retrieval steps. The span’s output shows what the model was given to work with, which is where RAG debugging usually starts.
• Embedding spans for embedding calls.
• LLM spans for the synthesis model calls, with the model, token usage and messages.
• Cost per model call, computed by Rius from the model and token counts. Costs are list-price estimates in US dollars, not billed amounts.

Retrieved document content and messages are content attributes. Set RIUS_CAPTURE_CONTENT to false to strip them at export. Document ids and scores stay visible even with content stripped.

When something else fits

If your pipeline uses LlamaIndex.TS, Rius has no LlamaIndex integration for it. The OpenAI integration still traces the provider calls made through the OpenAI client, and observe or startAsCurrentSpan (for example a RETRIEVER span) covers the pipeline around them. For other frameworks, the Integrations page shows which ones have Python or TypeScript support.

Related