How do I see retries and fallbacks in an agent built with LlamaIndex?
Rius shows a retry or fallback in a LlamaIndex agent as an errored span followed by the span that succeeded, and the trace page collapses a retry chain into one row. The LlamaIndex integration records your retrievers, embeddings and model calls on its own. Retry and fallback logic that you write yourself needs a span of its own, which you add with observe. A run that errored on the way but finished clean is badged recovered in the trace list.
How it works
Two layers make a retry visible.
What the integration records. With the LlamaIndex integration on, a query becomes a nested trace of typed spans. Retrieval steps are RETRIEVER spans, embedding calls are EMBEDDING spans, and synthesis model calls are LLM spans with model, token usage and messages. Cost is computed by Rius. The LlamaIndex integration page covers the details. This integration is Python only.
What you add. Retries and fallbacks you code around a query engine, such as a loop that tries again or a second engine that takes over, need a span of their own. Wrap each attempt in observe, and each attempt becomes its own span in the trace. A bare observe makes a CHAIN span named after the function. If the step you retry is a tool that no integration already records, trace it with kind=SpanKind.TOOL instead. That makes an execute_tool span named after the tool, which is the span kind the Tool kind filter and the Tool Loop alert look at.
Where it shows. On the trace page, in the waterfall:
- A failed span is highlighted along the path from the root to the error, so the attempt that failed stands out.
- Back-to-back calls of the same tool or step with the same input collapse into one row such as
fetch_article · 3 attempts · recovered, when every attempt but the last failed. Expand the row to see each attempt. Repeated calls that all succeeded stay separate rows. - A trace is
failedwhen at least one span has anERRORstatus. If the root span finished without an error of its own, the trace is badged recovered: child spans errored, the agent retried or fell back, and the run completed clean. The errors are still counted.
A fallback to a different function is a different step, so it appears as its own span next to the errored one rather than inside a retry row.
Set it up
-
Install the LlamaIndex integration, which installs the instrumentation and not
llama-indexitself:pip install "glassflow-rius[llama-index]" llama-indexSee Integrations for how integrations are enabled and which ones exist for other frameworks.
-
Call
rius.initonce, then wrap each attempt and the function that decides between them. The names below are yours, and the two engines stand for query engines you already built:import rius rius.init(api_key="ri_...", service_name="my-agent") # primary_engine and fallback_engine are query engines you already built, # for example index.as_query_engine() @rius.observe def ask_primary(query: str) -> str: return primary_engine.query(query).response @rius.observe def ask_fallback(query: str) -> str: return fallback_engine.query(query).response @rius.observe def answer(query: str) -> str: try: return ask_primary(query) except Exception: return ask_fallback(query)For a plain retry, wrap the single attempt in its own named function and call it from your loop. Calling the same function with the same input is what lets the trace page group the attempts into one retry row.
-
Run a query that triggers the failure path, then open the trace in the console. Use Traces to find the run, or the Spans tab with a status filter to list failed spans directly. The All kinds menu narrows the list to one kind of step.
-
Select the errored span. For an error span, the detail panel leads with the exception and traceback. The Input / Output tab shows the prompt and completion when content is captured. Use the previous and next buttons, or
]eand[eon the keyboard, to step between failed spans.
What you get
- Each failed attempt as a highlighted span, with the exception and traceback in its detail panel.
- A retry loop that reads as one row with its attempt count and recovered, instead of a wall of identical spans.
- A recovered badge on runs where the root span finished clean after child spans errored, so you can tell a run that healed itself from a genuine failure.
- The LlamaIndex steps around the failure: which retriever returned what, and which model call ran with how many tokens and what estimated cost. Costs are list-price estimates in US dollars.
- A way to compare the open trace against another run of the same agent, side by side, to see which steps were added or dropped.
For how to read traces across a whole agent, see Monitor AI agents in production. For every filter, tab and view mentioned here, see Exploring traces.
When something else fits
- If your agent is written in TypeScript, there is no LlamaIndex integration. The OpenAI integration still traces provider calls, and manual generations cover the pipeline around them.
- If the retries you care about are the model client’s own, they do not show as separate spans. LlamaIndex’s
OpenAILLM handsmax_retries(3 by default) to the OpenAI client, which retries inside one call, so you see one LLM span, failed only if the last attempt failed. Setmax_retries=0and retry in your own wrapped function if you want a span per attempt. - If you only need to know that a run recovered, the recovered badge in the trace list is enough, and no extra spans are needed.