What is Trace?

Trace is Molar's forensic replay surface. Guard checks, Cartographer agent runs, and manual CI uploads produce a canonical NDJSON record — video, DOM mutations, network, console, clone state, and agent thoughts — that engineers scrub, share, and hand off to Mender after a fix is confirmed.

Product page: trace.molar.it · Trace SKU viewer: trace.molar.it/traces · Full forensic UI: app.molar.it/trace · Combined hub: app.molar.it

What ships today

Trace captures every run as a canonical NDJSON record. Open traces at trace.molar.it/traces or the full forensic UI at app.molar.it/trace.

Hosted customers at app.molar.it do not operate capture workers. Self-hosted operators use the worker stack in Workers & ingestion.

Replay every failure, like a debugger

Trace replaces the download-trace-zip / grep-logs / re-run-suite loop with a cloud-native forensic record where signals share one timeline.

Trace is where engineers watch, scrub, compare, and ask questions about a single test run — not where they author scenarios, gate PRs, crawl apps, or operate clone fleets. Those jobs belong to Cartographer, Guard, and Clones.

The five ribbons

Every trace exposes five parallel timeline ribbons locked to one monotonic playhead. Click anywhere on the scrubber and every panel jumps together — no desync between video and network logs.

A sixth signal — clone state — appears in the inspector Clones tab and on the timeline at step boundaries. Because Molar owns stateful vendor simulators, Trace can show exactly what Stripe, Twilio, or email clones returned at each step.

The hero preview on trace.molar.it shows this layout: step 7 selected, a failed network tick on the NETWORK ribbon, console errors aligned at the same timestamp, and agent attribution trailing the failure.

Layer 1 — visual forensic replay

Layer 1 is the visual replay viewer. It answers: what happened during this run? Video, events, and share links ship on trace.molar.it today; the full five-ribbon scrubber and DOM/Source modes ship on app.molar.it/trace.

Viewer modes

Three center-panel modes share one scrubber:

Layer 1 also includes the nine inspector tabs (Overview, Events, Network, Console, Clones, Agent, Debugger, Replay, Artifacts), keyboard shortcuts, share links, and markdown export. See Trace detail for the full layout.

What Layer 1 captures

Trace writes a canonical NDJSON event stream (zstd-compressed) alongside:

• trace.playwright.zip — opens in npx playwright show-trace
• video.webm — hot-tier screencast
• summary.json — denormalized metadata for list views and search
• Content-addressed blobs — global SHA-256 dedup for DOM, bodies, screenshots

Capture hooks live in @molar/trace-capture. Cartographer and Guard runners attach capture automatically. You can also upload bundles via the ingest API. See Workers & ingestion.

Layer 2 — deterministic replay from step N

Layer 2 adds deterministic re-execution from any step in a failed run. An engineer selects step N, edits the scenario or source file inline, and re-runs from that point with clone state, RNG seeds, virtual clock, and recorded network responses restored — without re-running steps 1…N−1.

The result is a child trace linked to the source via parent_trace_id. A side-by-side diff view highlights network, DOM, clone state, and console changes. Layer 2 requires the source trace to be in hot tier (or restored from cold — typically 30–90 seconds).

Layer 2 supports single-clone scenarios today. See Debugger & replay for the full workflow.

Debugger AI — run-scoped forensic chat

The Debugger is a conversational agent scoped to one trace's artifacts. It reads NDJSON slices, clone snapshots, and source files — it does not open PRs (that is Mender's job).

On every new failed trace, Debugger auto-generates a one-paragraph forensic summary from the failure signature, last assertion, last network error, and any existing Mender classification. Follow-up questions cite (seq:N) event references so claims are auditable.

Example exchange:

Engineer: why did step 7 fail?

Debugger: Step 7 clicked "Upgrade to Pro" successfully, but the Stripe webhook returned 404. The webhook URL in config points to /api/stripe/webhook while the route handler lives at /api/webhooks/stripe — renamed in PR #4521. Want me to trigger a Layer 2 replay with the corrected URL?

Debugger can also trigger Layer 2 replays with explicit user confirmation. Budget caps and cheap mode (Haiku) are configurable per org. Use REST or MCP — see Debugger & replay.

Portfolio position in Molar

Trace sits at the evidence layer of the Molar stack. Other products produce traces; Trace consumes, displays, shares, and hands off fixes.

Cartographer ──▶ scenarios + agent runs
       │
       ▼
    Guard ──────▶ PR checks + prod monitor ──▶ traces (NDJSON)
       │                                              │
       ▼                                              ▼
   Clones ◀────────────────────────────────────── Trace
  (state)                                    (viewer + Debugger + L2)
                                                      │
                                                      ▼
                                                   Mender ──▶ fix PR

Combined mode (app.molar.it): shared Better Auth session, app switcher, and hub widgets (recent failures, shortId search) that deep-link into Trace — the full viewer never embeds inside the central hub.

Standalone mode (trace.molar.it): full Trace SKU with org billing scoped to Trace meters (storage GB-month, share-link egress, Debugger LLM cents, Layer 2 replay minutes).

Deployment modes

Local standalone requires TRACE_ENCRYPTION_KEY and runs without the full Cartographer stack. See Quick start.

Artifact format at a glance

Each trace stores under traces/runs/{org_id}/{yyyy}/{mm}/{dd}/{trace_id}/:

Retention tiers: hot (full fidelity) → warm (video + logs) → cold (summary + screenshot). Failed runs are auto-pinned to hot until archived. Pinning blocks tier-down indefinitely.

Security and compliance

• PII masking via scenario frontmatter (mask_inputs, mask_text, network_redact)
• Org-scoped RLS on all API queries; signed URLs for blob access
• Public share links opt-in with configurable expiry (default 7 days)
• Debugger uses GitHub App token — not user OAuth — for source reads

Details: Security.

Documentation map

Start here: Quick start — get a trace on screen in five minutes.