Skip to Content

I trace LlamaIndex with Helicone. How do I switch to Rius?

Rius traces LlamaIndex after one rius.init call, so you replace the Helicone proxy or logger and get each query as a nested trace with tokens and cost. Install the llama-index extra, call init, and build your indexes and query engines as before. The LlamaIndex integration is Python only. Rius is not a gateway, so caching, rate limits and fallbacks stay where they are today.

How it works

Helicone logs calls on the network path, through a base URL and Helicone-Auth header, or through its async logger. Rius works inside your process. The LlamaIndex integration instruments LlamaIndex itself, so nothing sits between your code and the provider.

A query becomes a nested trace of typed spans:

  • Retrieval steps are RETRIEVER spans. The retriever span’s output shows what the model was given to work with.
  • Embedding calls are EMBEDDING spans.
  • Synthesis model calls are LLM spans with the model, token usage and messages. Rius computes cost on its side from the model and tokens, as a list-price estimate in US dollars.

If the openai extra is also installed, the chat or completion call is traced as a second LLM span under the LlamaIndex span. With glassflow-rius 1.1.1 or later, that call is counted 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, so their OpenAI span starts a trace of its own.

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

Set it up

  1. Install the instrumentation. The extra installs the integration, not llama-index itself, so a fresh environment names both:

    pip install "glassflow-rius[llama-index]" llama-index
  2. Remove the Helicone pieces that traced your LlamaIndex calls. If you used the async logger, delete it. Do not run both tools in one process: both register the process-wide OpenTelemetry tracer provider, only the first registration is kept, and your calls reach only one tool.

    # Before: Helicone async logger from helicone_async import HeliconeAsyncLogger logger = HeliconeAsyncLogger(api_key=HELICONE_API_KEY) logger.init()
    # After: Rius SDK import rius rius.init(api_key="ri_...", service_name="my-agent") # build indexes and query engines exactly as before
  3. If your model client points at a Helicone base URL with a Helicone-Auth header, keep it for now so both tools see the same calls (see the side-by-side note below). Once you have compared, go back to the provider’s default client and your own provider key. If you used AI Gateway with Helicone-managed keys or credits, switch to your own provider keys first, because Rius never holds provider keys.

  4. Move your Helicone headers onto Rius scopes. Replace Helicone-Session-Id with rius.session() and Helicone-User-Id with rius.user(). Replace Helicone-Property-* values with span attributes set on the span that wraps the work. Here query_engine and question are your own:

    with rius.session(session_id): with rius.user(user_id): with rius.start_as_current_span("support_ticket") as span: span.set_attribute("app.ticket_id", ticket_id) answer = query_engine.query(question)
  5. Run one query and open the trace in the console. You should see nested spans with the LLM leaf carrying model, tokens and cost.

To compare both backends on the same traffic, keep the Helicone base URL in place and add rius.init() anyway. Rius patches the client library in your process, so calls are traced whatever base URL the client uses. Use plain model names such as gpt-4o-mini, not the gateway’s gpt-4o-mini/openai form, or calls show tokens but no cost. A response Helicone serves from its cache is recorded in Rius like any other call, so Rius cost runs higher than Helicone’s by your cache-hit share. The Helicone migration guide has the full cutover checklist.

What you get

  • A trace per query with the full tree of retrieval, embedding and model steps, not only the LLM requests Helicone logged.
  • Model, input and output tokens and cost on each model call, with cost computed by Rius.
  • Sessions and users: the Users page lists each user with their traces, failures, error rate and cost.
  • Custom properties as span attributes you can filter in the trace list.
  • Alerts with webhook, email and Slack channels.
  • Retrieved document content and messages are content attributes. The privacy controls cover them, and capture_content=False strips prompts and completions at export while metadata still flows.

Existing traces stay in Helicone. Rius starts from the first span you send it.

When something else fits

  • If you rely on caching, rate limits, retries or fallbacks, keep the Helicone gateway in front of the provider and add Rius next to it. Rius traces the calls either way.
  • Rius has no prompt management, scores, feedback, datasets or evals, so keep those workflows in their current tool.
  • If your app uses LlamaIndex.TS, see the integrations list for what is covered, or trace calls with manual generations. For other tools, start from Migrate to Rius.

Still stuck? Get help

Last updated on