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. During voltro dev, the browser console bridge also forwards browser console lines into that buffer.

The browser-to-inspect bridges are deliberately limited to development builds. Setting localStorage.framework_debug = '1' in a production bundle enables the local [fw …] connection timeline only; it never starts clientLog POSTs or an inspect EventSource. In development, both diagnostic transports are single-flight, rate-limited, and bounded: permanent 4xx responses disable them for the page, while transient failures use exponential backoff and open a circuit after five consecutive failures. The SSE relay probes status and content type before creating an EventSource, then explicitly closes a failed source before a bounded retry.

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 }.

#Development store-change attribution

When development debug logging is enabled, voltro:dev:store records keep their op and table fields. Changes to _voltro_schedule_claims additionally include task (the schedule name) and bucket when present and valid. Inserts use the new row image; deletes use the old one. Other table logs are unchanged. Full rows, payloads, actor fields and claim IDs are not logged. Missing, malformed or overlong metadata is omitted, not inferred from a claim ID.

To inspect already-emitted records:

voltro logs --scope 'voltro:dev:store' --level debug --since 30s --format json

The JSON record's fields can contain:

{
  "op": "insert",
  "table": "_voltro_schedule_claims",
  "task": "voltro.workflow.admission",
  "bucket": "2026-09-20T10:00:00"
}

These are delivered row changes, not SQL statement counts. One bulk DELETE may emit multiple row records; remote/CDC changes may also be delivered here. Task attribution explains the record without an extra database query. It neither suppresses events nor changes task cadence or database work.

#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.