CLI — Traces

The rivano traces subcommands give you terminal-level access to observability data — useful for debugging a production incident, reviewing recent activity, or running spot checks in CI.

List traces

rivano traces list

Output:

ID                   AGENT                  STATUS    DURATION    COST        CREATED
trace_xyz789         contract-summarizer    success   312ms       $0.0041     2 minutes ago
trace_abc123         support-classifier     error     89ms        $0.0000     5 minutes ago
trace_def456         contract-summarizer    success   445ms       $0.0063     12 minutes ago
trace_ghi012         code-reviewer          success   891ms       $0.0112     1 hour ago

Filter flags

# Filter by agent
rivano traces list --agent contract-summarizer

# Filter by status
rivano traces list --status error

# Filter from a date
rivano traces list --since 2026-04-01

# Combine filters
rivano traces list --agent contract-summarizer --status error --since 2026-04-01
FlagDescription
--agent <name>Filter to traces for a named agent
--status <status>success or error
--since <date>ISO 8601 date or relative value (e.g. 2026-04-01)
--limit <n>Number of results (default: 20)

Get a single trace

rivano traces get trace_xyz789

Output:

Trace: trace_xyz789
─────────────────────────────────────
Agent:         contract-summarizer
Status:        success
Duration:      312ms
Cost:          $0.0041
Input tokens:  142
Output tokens: 87
Environment:   production
Created:       2026-04-04T14:22:00Z

Spans:
  ✔ policy/block-injection      1ms    pass
  ✔ provider/openai             306ms  200 OK
      model: gpt-4o
      input_tokens: 142
      output_tokens: 87
  ✔ policy/redact-pii-response  3ms    pass

Scores:
  faithfulness:  0.91
  relevance:     0.87
💡

The span breakdown shows exactly where time was spent. If provider/openai is consistently slow, consider switching to a faster model or enabling response caching in the gateway.

Aggregate stats

rivano traces stats

Output:

Trace Stats (all time)
─────────────────────────────────────
Total requests:     1,847
Success:            1,802  (97.6%)
Error:              45     (2.4%)
Avg duration:       381ms
Total cost:         $24.18
Total input tokens: 421,094
Total output tokens: 312,771

Filter stats to a time window:

rivano traces stats --since 2026-04-01

Filter stats to one agent:

rivano traces stats --agent contract-summarizer --since 2026-03-01

Using —json for scripting

# Get the last 5 error traces as JSON
rivano traces list --status error --limit 5 --json

# Extract just the trace IDs
rivano traces list --json | jq -r '.data[].id'

# Check current error rate
rivano traces stats --json | jq '{total, error, errorRate: (.error / .total * 100)}'
  • SDK Traces — Programmatic trace queries with full filter options
  • CLI Diagnostics — High-level health summary with rivano status
  • SDK Costs — Aggregate cost breakdowns by agent and model
Previous ← CLI — Policies Next CLI — Deploy →