How do I search my AI agent traces by an attribute?

Rius lets you search traces by any attribute your agents send, using Add filter on the Traces page: you pick a field, an operator and a value. The same filters work on the Spans tab, from a single span, and as saved searches you can reuse. Filters combine with AND and live in the URL, so a copied link opens the same filtered list.

How it works

The search box and the filter builder do different jobs.

• Search box on Traces. It matches trace names and IDs within the traces already loaded, so load more pages to search further back.
• Search box on Spans. It searches the whole time range and matches span names, span IDs, trace IDs and session IDs. Paste a session ID to list every span in that session.
• Filter builder. For anything else, click Add filter and pick a Field: a trace column, or any span or resource attribute your agents send. Each attribute shows how many spans carry it in the current window.
• Operators. is, is not, is any of, is none of, exists, does not exist, and for numbers greater than, at least, less than, at most, and between.
• Values. Pick one from the suggestions, or type one and use it as typed. Suggestions leave out payload attributes such as prompts, completions and tool input and output, and very long values, so type those yourself.

Attribute filters match exact values only, so there is no partial match on an attribute. An attribute that your workspace has not declared is filtered as text and offers the equality and existence operators. Declare it with a type to get the numeric operators and a readable label.

The Spans tab is the same list at span granularity. Use the All kinds menu (Agent, LLM, Tool, Retriever, Embedding, Chain, Other) to look at one kind of step, such as every tool call or every LLM call to a given model.

Set it up

1. Send the attribute from your agent. Any span or resource attribute shows up as a field in the filter builder. The shared setup is in Monitor AI agents in production.

import rius
 
rius.init(api_key="ri_...", service_name="my-agent")
 
with rius.start_as_current_span("lookup_order") as span:
    span.set_attribute("customer.tier", "gold")

2. Open Traces, pick a time range (15m, 1h, 1d, 7d by default, 30d or custom), and click Add filter.
3. Choose the Field, the Operator and the Value. The filter becomes a chip you can edit or remove. Add more chips to narrow the list further.
4. To filter from something you are already reading, open a span and go to its Raw tab. Every attribute has a menu with Filter traces by this, Exclude this value, Copy key and Copy value. Admins also get Declare this attribute…, which declares the key for the workspace with a type and a label guessed from the value.
5. To keep a search, open Saved on the Traces filter bar and choose Save current search…. It stores the filters, the search text, the status and agent selections, and the time range. A relative range such as the last 7 days moves with you instead of freezing to the day you saved it.
6. Choose who sees the saved search: Only me, the default, or Everyone in this workspace. Delete it from the same menu.

The full walkthrough of the list, the waterfall and the span panel is in Exploring traces.

What you get

• A list narrowed to exactly the runs you care about, such as one agent version, one end user or one model, with a summary strip above it showing count, error rate, latency percentiles, tokens and cost for the matches.
• A status filter built from the spans themselves: completed, failed, or incomplete, which the badge shows as running…. A trace that still reads running… long after the work should have finished points to a crash or a hang, and it appears only when partial spans are enabled.
• Clicks that filter for you. Selecting a user, sender or agent cell filters the list to it, and the Session link in a trace header opens Spans filtered to that session.
• Links that carry the view. Because filters live in the URL, a copied link opens the same filtered list.
• Searches your team shares. Saved searches can be visible to everyone in the workspace.
• A frozen copy for people outside the workspace. Share on the trace list creates a read-only link to the current time range, status filter and filter chips, with an expiry of 24 hours, 7 days or 30 days. It carries summary tiles and trace metadata only, never span content.

When something else fits

• If you want to look at one run in depth rather than find it, open the trace and use the waterfall or the Map tab, which are covered in Exploring traces.
• If you need a partial match on attribute text, the filter builder will not do it, because attribute filters match exact values. Use the search box for names and IDs, and type the full value for an attribute.
• If you need to hand a failure to someone outside the workspace, use Share instead of a saved search.

Related