Trace a session run
Turn on the forensic trace recorder with BL_TRACE and get a local, redacted, per-run record of everything a session did.
Set BL_TRACE and browserlane records every session run as a forensic
trace — a local folder holding the run's metadata, an append-only event log
of every command with its arguments, result, duration, and errors, and
(depending on level) screenshots and browser events. Traces are written to
your machine only, never uploaded, and secrets are redacted at write time.
Tracing is off by default with zero overhead — there is no CLI flag; the only switch is the environment variable. An unset or unrecognized value means no trace is written.
Turn it on
BL_TRACE is read by the process that hosts the session — usually the daemon,
which inherits the environment of whichever command auto-started it. If the
daemon is already running, exporting the variable in your shell does nothing;
you have to restart the daemon with the new value:
Stop the running daemon
bl daemon stopRelaunch with a trace level
The next command auto-starts a fresh daemon that carries the variable:
BL_TRACE=forensic bl open example.comOr as one line:
bl daemon stop && BL_TRACE=forensic bl open example.comFind the trace
Every session run gets its own directory under the cache dir's
traces/ folder, named <utc-timestamp>-<session>-<id>:
traces/20260705-183042-default-a3f19c/
├── metadata.json # run metadata, rewritten in place as it changes
├── events.jsonl # append-only event log, one JSON object per line
└── artifacts/ # screenshots etc. referenced from eventsOne trace per run, not per name
A trace records a single run of a session. After a run ends, the next
command for the same session name opens a fresh trace directory — two
default traces are two distinct runs, not one continuing session.
Capture levels
BL_TRACE | What gets recorded |
|---|---|
| unset / anything else | Nothing — tracing is off, zero overhead. |
normal | Session lifecycle plus every CLI command / MCP tool call: sanitized arguments, results, durations, and errors. |
debug | Everything in normal, plus browser events over BiDi — console messages, network metadata, navigations, dialogs, downloads — and post-action screenshots. |
forensic | Everything in debug, plus redacted response headers, failure screenshots, and larger size caps. |
Where traces live
Traces go under the browserlane cache directory, next to the daemon's runtime files:
| OS | Location |
|---|---|
| macOS | ~/Library/Caches/browserlane/traces/ |
| Linux | ~/.cache/browserlane/traces/ |
| Windows | %LOCALAPPDATA%\browserlane\traces\ |
Set BROWSERLANE_CACHE_DIR to move the cache root (and with it, traces/)
somewhere else.
Redaction is always on
There is no raw-capture mode — redaction happens at write time, on every level:
- Values under sensitive key names (tokens, passwords, secrets, …) are redacted at any depth in arguments and results.
- JWTs and card numbers (Luhn-checked) are caught wherever they appear.
- Values typed into sensitive form fields never reach the event log.
- Long values are truncated to per-level size caps.
Screenshots show the rendered page
Redaction covers the structured event data. Screenshots captured at debug
and forensic levels show the page as rendered — including anything visible
on screen — so treat trace folders with the same care as screenshots.
How a run ends
metadata.json records how each run finished. A cleanly stopped run carries a
stop_reason telling you why:
stop_reason | The run ended because |
|---|---|
bl.stop | bl stop closed this session's run (daemon and other sessions keep going). |
session.close | bl session close removed the session. |
session.reset | bl session reset reset the session to a fresh state. |
daemon.stop | bl daemon stop shut everything down. |
idle.eviction | A named session was auto-evicted after the daemon idle timeout. |
A run can also end cleanly without an explicit stop — for example, when the
process hosting the session exits normally. That trace records an end marker
with its exit status but no stop_reason.
A trace with no end marker means the process died mid-run — the run is treated as crashed, and everything logged up to that point is still on disk. That's the point of append-only: the trace survives exactly the failures you want to inspect.
What gets traced
Per-command events are recorded for CLI commands (via the daemon) and MCP tool
calls. Runs hosted by bl serve or bl pipe do not get per-tool events.
Viewing traces
Everything in a trace is plain JSON — metadata.json and events.jsonl read
fine with jq or any editor. A dedicated viewer, BrowserLane Inspector —
a desktop app for browsing, filtering, and triaging these traces — is in
development: see /inspector.
Related
- Record a session — a Playwright-compatible trace of a deliberate start/stop recording, rather than an always-on run log.
bl daemonandbl stopin the CLI reference.- The daemon & the visible browser — why the environment variable belongs to the daemon, not your shell.