Every run on Sublayr is traced automatically, with no setup or instrumentation required. A trace captures the complete lifecycle of a single agent run — every input, decision, tool call, and outcome — in the order it happened. This guide covers reading and interpreting traces.

What's in a trace

A trace is a sequence of timestamped steps. A typical trace for a support agent handling a refund might look like:

09:41:02 — Received request: "Refund order #48213"
09:41:03 — Retrieved knowledge (3 sources)
09:41:04 — Decided action: refund, amount: $42.00
09:41:04 — Approval required (policy: refund-policy)
09:41:58 — Approved by: Sarah (Finance)
09:41:59 — Called tool: stripe.refund
09:42:00 — Tool response: success
09:42:00 — Resolved

09:41:02 — Received request: "Refund order #48213"
09:41:03 — Retrieved knowledge (3 sources)
09:41:04 — Decided action: refund, amount: $42.00
09:41:04 — Approval required (policy: refund-policy)
09:41:58 — Approved by: Sarah (Finance)
09:41:59 — Called tool: stripe.refund
09:42:00 — Tool response: success
09:42:00 — Resolved

09:41:02 — Received request: "Refund order #48213"
09:41:03 — Retrieved knowledge (3 sources)
09:41:04 — Decided action: refund, amount: $42.00
09:41:04 — Approval required (policy: refund-policy)
09:41:58 — Approved by: Sarah (Finance)
09:41:59 — Called tool: stripe.refund
09:42:00 — Tool response: success
09:42:00 — Resolved

Each step includes a timestamp, a duration, and — when you drill in — the full payload sent to and received from the model or tool at that step.

Viewing a trace

Via the dashboard, click into any run under Observability > Runs. Via CLI:

sublayr traces get run_9f21

sublayr traces get run_9f21

sublayr traces get run_9f21

Via API:

GET /v1/runs/run_9f21/trace

GET /v1/runs/run_9f21/trace

GET /v1/runs/run_9f21/trace

Filtering traces

Find traces matching specific criteria — useful when investigating an issue across many runs:

sublayr traces list --agent agt_4b81 --status failed --since 24h

sublayr traces list --agent agt_4b81 --status failed --since 24h

sublayr traces list --agent agt_4b81 --status failed --since 24h

Common filters include agent ID, status (success/failed/pending), date range, and whether a run required approval.

Understanding failure traces

When a run fails, the trace shows exactly which step failed and why — a tool returning an error, a model timing out, a guardrail blocking an action. This is typically enough to diagnose the issue without needing to reproduce it manually, though Replay (see the next article) lets you step through the exact failure interactively.

Trace retention

Trace retention varies by plan: Starter retains basic traces for 30 days, Growth retains full traces with replay for 90 days, and Enterprise supports extended retention up to 2 years for compliance and audit purposes.

Exporting traces

For compliance or analysis outside Sublayr, export traces as JSON or CSV:

sublayr traces export --agent agt_4b81 --since 30d --format json

sublayr traces export --agent agt_4b81 --since 30d --format json

sublayr traces export --agent agt_4b81 --since 30d --format json