Traces CLI

Use provon traces to query API-backed trace summaries, inspect spans, export evidence, and aggregate project telemetry. API-backed trace commands require a project credential with telemetry:read. Local source-based diagnosis uses provon diagnose and needs no API key.

View as Markdown Open the plain-text version of this page.

Prerequisites#

Authenticated CLI and a selected project (see Authentication).
The key includes telemetry:read.
For self-hosted targets, PROVON_API_URL points at the server (default: https://api.provon.dev).

List Traces#

provon traces list --range 6h --limit 20

Option	Meaning	Default
`--range <range>`	Relative range such as `30m`, `6h`, `24h`, `7d`	`1h`
`--limit <n>`	Maximum trace summaries	`20`
`--cursor <cursor>`	Opaque cursor from the previous response	—
`--query <text>`	Search text	—
`--search-type <types>`	Comma-separated search fields	`trace-id,span-name,operation-name,content`
`--level <levels>`	Comma-separated `ok`, `error`, `unknown`	—

Search Traces#

Search retained content, inputs, outputs, and identity fields:

provon traces search "permission denied" \
  --search-type content,input,output \
  --level error \
  --range 24h

Search types: trace-id, span-id, user-id, conversation-id, span-name, operation-name, content, input, output.

Use exact identity search when you already have an id:

provon traces search "$TRACE_ID" --search-type trace-id --range 7d
provon traces search "repair-42" --search-type conversation-id --range 7d

Inspect A Trace#

Fetch all normalized spans:

provon traces get <trace-id>

Fetch the compact overview with paged span summaries (default page size 100):

provon traces overview <trace-id> --limit 100

Continue a large overview with the cursor from nextSpanCursor:

provon traces overview <trace-id> \
  --limit 100 \
  --cursor "<nextSpanCursor>"

traces get returns complete normalized spans and is not paginated. Use overview first for large traces when only identity, timing, status, usage, cost, and previews are needed.

Fetch a single span:

provon traces span <trace-id> <span-id>

Summarize A Trace#

provon traces summarize <trace-id> --top 5

Returns duration and span counts, failed span count, token and cost totals when available, provider/model dimensions, the slowest spans (default top 5), and failed span details. --limit (default 200) controls how many span summaries are fetched for the summary.

traces summarize does not run diagnostic Rules and does not generate Findings; use provon diagnose for that.

Export Evidence#

Export an API-backed trace to a local bundle for investigation or a coding agent:

provon traces export <trace-id> --out ./trace-evidence

The bundle contains:

manifest.json
trace.jsonl
spans.jsonl
overview.json
git_context.json

git_context.json records the current repository, branch, commit, remote, and dirty paths when the command runs inside a Git repository; it does not copy repository content.

Option	Meaning	Default
`--out <dir>`	Output directory (defaults to `<trace-id>-trace`)	—
`--force`	Overwrite files that already exist	off
`--overview-page-size <n>`	Span-summary page size	`500`
`--no-git-context`	Skip local Git context capture	off

Aggregate Statistics#

provon traces stats
provon traces stats --range 24h --level error

stats defaults to the 1h range and supports --query, --search-type, and --level.

Conversations And Users#

provon traces conversations --range 24h --limit 20
provon traces conversations --search "payment" --user-id <user-id>
provon traces conversation-traces <conversation-id>
provon traces users --range 24h

Default limits: conversations and users 20; traces for one conversation 50.

Success Check#

provon traces list --range 1h

A healthy result returns ok: true with a data.items array (possibly empty when no traces exist yet). Use provon traces search "<known-id>" --search-type trace-id to confirm a specific trace landed in the project.

Common Workflows#

Investigate An Error#

provon traces search "run-tests" \
  --search-type span-name,content \
  --level error \
  --range 24h

provon traces overview <trace-id>
provon traces get <trace-id>

Hand Evidence To A Local Diagnosis#

provon traces export <trace-id> --out ./trace-evidence
provon diagnose ./trace-evidence

diagnose evaluates the same Rule definitions locally, uploads nothing, and does not persist Findings; see Diagnose.

Troubleshooting#

Symptom	Likely cause	Fix
`HTTP_403` on every traces command	Key missing `telemetry:read`	Recreate the key with the capability
Empty `items` with correct time window	Range too narrow or wrong project	Widen `--range`; verify with `provon project current`
Cursor errors after `overview`	Stale cursor from an earlier page	Restart pagination from `overview <trace-id>` without `--cursor`
`export` fails on existing directory	Target directory has files without `--force`	Add `--force` or choose a new `--out` directory
Self-hosted traces missing	`PROVON_API_URL` points at the hosted default	`provon config set api-url <server-url>`