voltro traces & voltro logs

voltro logs and voltro traces give you the running app's log buffer and trace buffer from a shell — no DevTools UI needed. Both discover every running process via ~/.voltro/runtime-registry.json, fan out to each one's inspect endpoint in parallel, merge by timestamp, and render.

#voltro logs

Every voltro dev / voltro start instance buffers the last 2000 server-side @voltro/logger records and every browser console line that the dev console bridge forwarded.

voltro logs                                # last 100 from every running process
voltro logs --tail 50 --level error        # only errors, last 50
voltro logs --since 30s                     # last 30 seconds
voltro logs --scope 'orders'               # case-insensitive scope filter
voltro logs --filter 'channels.create'     # message substring
voltro logs --source client                # only browser-originated lines
voltro logs --trace <traceId>              # the WHOLE causal chain for one request
voltro logs --process voltroCloudApi       # restrict to one registry name
voltro logs --format json | jq '.[]'       # machine-parseable

Flags: --tail <n> (default 100, cap 2000), --since <spec> (30s / 5m / 1h / unix-ms), --level <l> (trace|debug|info|warn|error|fatal, minimum level), --scope <substr>, --source <server|client>, --filter <substr>, --trace <traceId>, --process <name>, --format <pretty|json|text> (default pretty), --no-color.

--format json returns one object per record: { ts, level, source: 'server'|'client', scope, message, fields }.

#voltro traces

Mirror of voltro logs for the trace buffer — a transient ring of 2000 records, no persistence.

voltro traces                            # 20 newest traces, pretty
voltro traces --errors                   # only traces containing an errored span
voltro traces --since 30s --tail 50      # recent
voltro traces --process voltroCloudApi   # restrict to one process
voltro traces --id <traceId>             # one trace, span waterfall (detail mode)
voltro traces --errors --format json | jq '.traces[]'

List-mode flags: --tail <n>, --since <spec>, --errors, --process <name>, --format <pretty|json> (default pretty), --no-color.

Detail mode (--id <traceId>, alias --trace) renders one trace's span waterfall and additionally accepts --min-duration <ms> and --status <ok|error|unset> to filter the spans shown.

Subscriptions vs requests in the output: traces from useMutation / useSubscription / actions / webhooks show spans · duration (the duration is the call's latency). Subscriptions show sub · N deliveries · last Xms — the open-duration is liveness, not latency, so the command surfaces the latency of the most recent data transfer instead (snapshot + each delta is its own span with its produce→push latency).

#The --trace <id> end-to-end chain

The whole point of the trace id is that it's shared across the entire frontend → api → api chain (see Distributed tracing). Once you have a traceId, you can pull the complete causal chain for one request across every hop, in order:

# 1. find a failure
voltro traces --errors --format json | jq '.traces[]'

# 2. pull the full chain for that one request
voltro logs --trace <traceId> --format json

That returns every log line of the request — frontend action → api Y → api Z — in order. It's the fastest answer to "where did this error come from?".

#For AI coding agents

Claude Code, Cursor, GitHub Copilot, and other agents: use these whenever you debug. Before you grep code or read the user's description of a bug, run voltro logs --tail 100 (or --since 30s after a reproducible action). The buffer carries the actual error message, the actual stack, the actual request/mutation tag — faster and more accurate than inferring what happened from source.

Common patterns:

• "Is the change working?" — make the edit, run the reproducing action, then voltro logs --since 10s. New errors show immediately.
• "Why did the mutation fail?" — voltro logs --filter '<rpcTag>' --level warn.
• "Is the browser even reaching the server?" — voltro logs --source client --tail 20.
• "Why did this request fail end-to-end?" — grab the traceId of a failed span (voltro traces --errors, or the dev error toast), then voltro logs --trace <id> --format json for the whole chain.

Discovery uses ~/.voltro/runtime-registry.json — every voltro dev / voltro start registers itself with a heartbeat. If nothing is running, both commands print a clear hint instead of failing. The trace buffer is transient; if you need older context than the ring holds, ask the user to reproduce the action.