Quick Start

Get your first trace on screen in about five minutes. This guide covers the local standalone runtime, cloud dashboard paths, and the minimum configuration for Guard-integrated capture.

Choose your path

Most production teams will use Guard auto-capture once wired; today use Cartographer runner capture or manual ingest.

Cloud — first trace via ingest

When Guard auto-capture ships, every check will produce a trace row automatically. Until then:

Step 1 — Confirm ingest access

1. Open app.molar.it → Settings → Tokens — mint an API key with traces:write
2. Or attach @molar/trace-capture in a Cartographer/Playwright runner (see Workers & ingestion)
3. Note your org slug for API calls

Step 2 — Produce a trace

Upload a bundle via API (POST /v1/traces/ingest) or run a scenario with capture attached.

Step 3 — Open the trace

Failed checks will deep-link from GitHub check annotations when Guard integration ships. Open the trace and select the failing step manually today.

Step 4 — Explore

On app.molar.it/trace/{id} (full UI):

• Scrub the five ribbons (STEP, NETWORK, DOM, CONSOLE, AGENT)
• Open the Overview tab for failure signature and source check link
• Press D for Debugger · Share for permalink

On trace.molar.it (SKU viewer today): Events, Video, Debugger, Share, and pin.

Next: Trace detail for the full viewer tour.

Local standalone

The standalone Trace package runs a self-contained runtime without Cartographer, Guard, or cloud dependencies. Use it for local development, smoke tests, and CI verification.

Prerequisites

• Node.js 20+
• npm or pnpm

Install and run

Download the standalone Trace bundle from your Molar account portal (or contact support@molar.it), then:

npm install
TRACE_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef npm run dev

Open http://localhost:4173.

The standalone server uses x-molar-org header for tenant scoping in tests and smoke runs.

Optional data directory

Persist traces across restarts:

TRACE_DATA_DIR=/tmp/molar-trace-dev \
TRACE_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef \
npm run dev

Verify the install

npm test
npm run test:browser
npm run smoke

Molar Cloud Trace runs on the same API and dashboard as Cartographer and Guard. The standalone package is the lightweight path for local build/verify without the full stack.

Dashboard paths (cloud)

Trace uses /traces as the canonical route — not /runs. Legacy /runs URLs redirect with 301.

Query params on trace detail:

Combined-mode users arrive from app.molar.it with a shared session cookie on .molar.cloud.

First trace in five minutes (manual ingest)

If Guard is not wired yet, upload a Playwright trace bundle manually.

Step 1 — Run a Playwright test with tracing

import { test } from "@playwright/test";

test("checkout smoke", async ({ page, context }) => {
  await context.tracing.start({ screenshots: true, snapshots: true });
  await page.goto("https://staging.example.com/checkout");
  // ... test steps ...
  await context.tracing.stop({ path: "trace.zip" });
});

Step 2 — Upload to Trace

curl -X POST "$TRACE_API/v1/traces/ingest" \
  -H "Authorization: Bearer $MOLAR_API_KEY" \
  -F "bundle=@trace-bundle.tar.zst" \
  -F "scenario_slug=checkout-stripe" \
  -F "source=manual" \
  -F "commit_sha=$(git rev-parse HEAD)"

Replace $TRACE_API with https://api.molar.it/trace and $MOLAR_API_KEY with an org API key (Settings → Tokens, scope traces:write).

Step 3 — Open in dashboard

The response includes id and short_id. Navigate to:

https://trace.molar.it/traces/{id}

Postprocess completes in seconds — P99 ingest to viewable is ~2.4s.

Environment variables

Local standalone

Capture library (Guard / Cartographer runner)

Cloud / self-hosted API

Scenario privacy (.molar.md frontmatter)

Configure per-scenario — not env vars:

privacy:
  mask_inputs: true
  mask_text: ".pii, .email"
  block: ".secrets-panel"
  network_redact:
    - "$.user.email"

See Security for PII handling details.

CLI shortcuts

# Open latest failed trace in browser (requires molar CLI + auth)
molar trace open --failed

# Open specific trace by short ID
molar trace open xY9zQ2mNp

What to do next

Demo trace: Open the demo trace on app.molar.it/trace — a pre-loaded failure at step 7 with webhook 404 signature (demo fixture when API is down).