How can my coding agent search spans across traces in Rius?

Your coding agent searches spans across traces in Rius with the list_spans tool on the Rius MCP server. It returns a table of matching spans from every trace in the workspace, not grouped by trace. Ask in plain words, such as “show me every errored tool call in the last day”, and your client picks the tool and its arguments.

How it works

list_spans is the cross-trace counterpart to get_agent_trace, which shows the waterfall of a single trace. Use it to find spans by kind, session or agent regardless of which trace they landed in, for example every failed tool call this week, or one session’s spans across however many traces it touched.

The main parameters:

• hours: a lookback window ending now, 24 by default. “This week” is hours: 168. start and end take absolute RFC3339 times and override it.
• kind: the span kind, one of llm, tool, chain, retriever, reranker, agent, embedding or other. A rerank call is reranker, not llm.
• status: Ok, Error or Incomplete.
• session_id: every span in one session, across all its traces.
• agent and instance: the span’s own agent, and one running copy of it.
• user_id or anonymous: the spans of one end user, or the spans that carry no end user. Pass one, never both.
• search: a case-insensitive contains match on span name, span id, trace id or session id.
• error_text: free text over the failure itself, so you find a failing span by what it said, such as “rate limit”.
• filters: a list of clauses, each with a field, an op and values, ANDed together.
• sort_field and sort_dir: sort by start_time (the default), duration_ms, tokens or cost, ascending or descending.
• limit and cursor: 50 rows by default, and a page token to fetch the next page.

The columns status, agent, service, model, span_kind, operation and session_id are cheap to filter on over any window. Filters on your own attributes, written attr.<key> or resource.<key>, cost roughly 10 times more and work only over windows of 31 days or less. Narrow with a column first, then add one. Call describe_search_catalog before you guess a key: it lists the fields and the keys your workspace has produced.

The workspace argument is optional. Omit it to use your default workspace.

Set it up

1. Connect your coding agent to the Rius MCP server. For Claude Code, run this once and complete the browser sign-in the first time a session uses the server:

claude mcp add --transport http rius https://mcp.eu.console.rius-glassflow.com/mcp

If you already use the Rius plugin, it registers the server as rius, so skip this step. For Codex, Cursor and other clients, and for headless agents that use a read-scoped API key, see MCP. Ingest keys cannot query.

2. Ask in plain words. Your client turns the question into a list_spans call:

   • “Show me every errored tool call in the last day.” becomes kind: tool and status: Error.
   • “All spans in session user-42-chat-7.” becomes session_id.
   • “Which model calls cost the most this week?” becomes kind: llm, hours: 168 and a sort on cost.

3. To see what your client sends, or to call the tool by hand, use the arguments directly:

{
  "name": "list_spans",
  "arguments": {
    "kind": "llm",
    "hours": 168,
    "sort_field": "cost",
    "sort_dir": "desc",
    "limit": 10
  }
}

4. Narrow a broad result by asking a follow-up. If you know a failure message, ask for spans whose error says “connection reset” and the client adds error_text. For a field you are unsure of, ask what you can filter on and the client calls describe_search_catalog.

Every tool and its arguments are in the tool reference.

What you get

• A Markdown table of spans, newest first by default, that your client renders as a table or summary.
• Rows from every trace in the workspace, so one question covers the whole fleet instead of one run.
• A kind column that holds the raw OTLP span kind (SERVER, CLIENT, INTERNAL and so on). This is separate from the semantic kind you filter on with the kind argument.
• session, agent and user_id columns. The agent column names the agents you can filter by, and a span whose run declared no agent shows its service name there. The user_id column is the span’s own end user.
• A next-page cursor when more spans match than limit. Pass it back as cursor for the next page.
• To go from a run to its full waterfall, ask for the matching traces with list_agent_traces, which returns a trace id column. Then ask for one of those traces and your client calls get_agent_trace. Add include_content there to see what an LLM, agent or tool span said, received or returned. Content appears only where the span was exported with it, so spans sent with content capture off carry nothing extra.

For a wider view of how to watch agents in production, see Monitor AI agents in production.

When something else fits

• Ask for list_agent_traces when you want one row per run, for example to separate runs that failed from runs that hit errors and recovered.
• Ask for agent_traces_summary or workspace_metrics_overview when you want totals such as error rate, cost and latency percentiles rather than individual spans.
• Ask for agent_error_groups when you want a page of failures grouped into their handful of causes.

Related