Traces

When your agent sends OpenTelemetry traces to Coval, each simulated or uploaded conversation carries its spans. These commands search across spans, summarize one conversation’s trace, and dump raw spans. search also accepts --input-json (inline JSON, @file, or - for stdin) for the full filter object; explicit flags override fields from the JSON. See Input JSON.

Search Traces

Search spans across conversations and return the matching conversations.

coval traces search [OPTIONS]

Option	Type	Default	Description
`--start-date`	ISO 8601	—	Include spans at or after this timestamp
`--end-date`	ISO 8601	—	Include spans at or before this timestamp
`--span-name`	string	—	Case-insensitive substring match on span name
`--provider`	string	—	Case-insensitive substring match on provider
`--status`	string	—	Match span status: `error`, `ok`, or `unset`
`--attribute-filter`	string	—	Attribute filter as `KEY:OPERATOR[:VALUE]`; repeat up to 10 times (see below)
`--duration-ms-min`	number	—	Minimum span duration in milliseconds
`--duration-ms-max`	number	—	Maximum span duration in milliseconds
`--agent-id`	string	—	Restrict results to one agent
`--test-set-id`	string	—	Restrict results to one test set
`--sort-by`	string	—	Result ordering: `newest`, `oldest`, `slowest`, or `fastest`
`--limit`	number	25	Results per page (1-100)
`--cursor`	string	—	Opaque `next_cursor` from a previous search response

--attribute-filter takes KEY:OPERATOR[:VALUE]. Supported operators:

Operator	Meaning	Takes a value
`eq`	Attribute equals the value	Yes
`contains`	Attribute contains the value	Yes
`gt`, `gte`, `lt`, `lte`	Numeric comparison	Yes
`exists`	Attribute is present	No

Output columns: Simulation Output, Run, Status, Matched / Total, Errors, Span Names, Providers

# Slow tool calls in the last day
coval traces search \
  --start-date 2026-09-15T00:00:00Z \
  --span-name tool \
  --duration-ms-min 2000 \
  --sort-by slowest

# Spans that errored for one agent, with a specific attribute
coval traces search \
  --agent-id ag_abc123 \
  --status error \
  --attribute-filter 'tool.name:eq:lookup_order' \
  --attribute-filter 'retry.count:exists'

Trace Summary

Summarize the trace data received for one conversation: span names and counts, timing and status distributions, structural integrity checks, and attribute key/type coverage. The summary never includes attribute values, prompt text, or tool arguments and results.

coval traces summary [OPTIONS]

Option	Type	Description
`--simulation-id`	string	Simulated conversation to summarize
`--conversation-id`	string	Uploaded conversation to summarize

Pass exactly one of the two IDs.

coval traces summary --simulation-id sim_abc123

Raw Spans

Return the raw spans recorded for a simulated conversation.

coval traces spans <simulation_output_id> [OPTIONS]

Argument	Type	Required	Description
`simulation_output_id`	string	Yes	Simulated conversation whose spans to return

Option	Type	Default	Description
`--limit`	number	50	Maximum spans to return (1-200)
`--offset`	number	0	Number of spans to skip (0-100000)

coval traces spans sim_abc123 --limit 200 --format json

Getting Started

Resources

Search Traces

Attribute filters

Trace Summary

Raw Spans

​Search Traces

​Attribute filters

​Trace Summary

​Raw Spans

Search Traces

Attribute filters

Trace Summary

Raw Spans