How can I see errors and exceptions for my AI agent?

Rius shows errors on spans that carry an OpenTelemetry ERROR status, with the exception and traceback at the top of the span details. A span with that status marks its trace as failed, and the waterfall highlights the path from the root span to the failing span. The trace list shows an error count for every trace, so you can find failures before you open one.

How it works

Rius derives trace status from the spans themselves, not from anything your agent reports separately. Three things on a span decide what you see:

• ERROR status. A trace reads failed when at least one of its spans has an OpenTelemetry ERROR status. This status is what makes the error count, the failed filter and the highlighted path appear.
• A recorded exception. Exceptions are recorded as standard OpenTelemetry span events. The span details panel for an error span leads with the exception and the traceback, so a span that has an ERROR status but no recorded exception shows the failure without that detail.
• error.type. In the SDK’s scoped forms, an exception gives the span ERROR status and an error.type automatically. You do not set either by hand.

Where each signal appears:

• Trace list. Each row shows status, error count and latency. The strip above the list shows the error rate for the traces that match your filters.
• Waterfall. Failed spans are highlighted along the path from the root to the error. The header shows the span and error counts for the whole trace.
• Span details. The panel for an error span opens on the exception and traceback.
• Map view. One of the lenses shows errors, so you can spot failing nodes on a deep trace.

A trace is badged recovered when child spans errored but the root span finished without an error of its own. This is the case when the agent retried or fell back and the run completed. The errors are still counted. Back-to-back retries of the same tool collapse into one row such as fetch_article · 3 attempts · recovered.

The concepts page defines spans, kinds and status in full.

Set it up

1. Send traces with the SDK scoped forms. This is the shared setup, covered in Monitor AI agents in production. The quickstart wraps the handler with rius.observe, so an exception raised inside it is recorded on the span with ERROR status and error.type:

import anthropic
import rius
 
rius.init(api_key="ri_...", service_name="my-agent")
claude = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
 
@rius.observe
def handle(query: str) -> str:
    response = claude.messages.create(
        model="claude-haiku-4-5-20251001",
        max_tokens=200,
        messages=[{"role": "user", "content": query}],
    )
    return response.content[0].text
 
handle("What should I check when a collector drops spans?")

2. If you use another OpenTelemetry setup, set ERROR status on the failing span and record the exception as a span event. Without the ERROR status, the trace stays completed and nothing is highlighted.
3. Do not swallow the exception inside the traced scope. If your code catches it and returns a fallback, no span gets ERROR status and the failure does not show. Let it propagate to the span that should fail, or set ERROR status on that span yourself.
4. Turn on partial spans to see crashes. A span normally reaches Rius once, when it ends, so a process that dies mid-run exports nothing. With partial spans on, a content-free snapshot is sent when each span starts:

export RIUS_PARTIAL_SPANS=true

5. Find the failures in the console. Open Traces and filter the status to failed, or open Spans and filter by status to list failing steps directly. In an open trace, press ]e and [e to jump to the next or previous failed span. Exploring traces covers the filters and keys.

What you get

• A failed badge and an error count on every trace row, plus an error rate for the current filters.
• The failing step located for you: the waterfall highlights the path from the root to the span that raised.
• The exception and traceback first in the span details, so you read the cause without opening Raw.
• A recovered badge that separates runs that retried and finished from runs whose root span failed.
• Crashed runs that stay visible. With partial spans on, a run whose process died mid-run stays as running… instead of vanishing. Filter on that status (the filter value is incomplete) to find runs that never finished.
• The same failures in the Spans tab and the map view, so you can start from a step kind or from a graph.

When something else fits

If you want to be told about failures instead of looking for them, Rius has pre-defined alerts such as Consistent Error Pattern and Swallowed Error, plus custom rules on error rate. If a failure leaves no ERROR status because your code handled it, you need to mark the span as failed in your instrumentation before it shows here.

Related