Skip to main content
By the end of this guide you will have gone from a production browser error to the line of your source that threw it, and to a timeline of what that user did first. You will also know whether your environment records a masked replay, and how to switch it on or off. Forge builds every hosted frontend with source maps and files them privately with the release. So an error from a minified bundle is grouped into an issue and resolved to your own files (source maps and issues). Each error also carries the id of the browser session it happened in.

Before you begin

  • A frontend deployed to a hosted environment that declares observability = forge.Observability {} (deploy a static site). The browser telemetry Forge scaffolds is enough. Sessions exist only for hosted environments.
  • obs:read in the organization (credentials).
The example is a static site whose Check out button throws a TypeError for a cart with no coupon.
1

Find the error

terminal
2

Read the source-mapped stack

terminal
The frames name your source files and lines, not the minified bundle. The hex id in parentheses is the frontend build that reported the error.
3

Open the session the error happened in

The issue’s latest event carries its session id:
terminal
The user landed on /, moved to /cart, and hit the error two seconds later. Paths have their query string and fragment removed. When a session has a recording, the header says so, and the console’s Sessions view plays it. The CLI never prints the recording.
4

Browse sessions that have a replay

terminal
On a hosted environment, this list shows only sessions with a recorded replay. A session without a replay still has a full timeline, so reach it from its issue as in the previous step. Filter with --user, --path and --since, up to 30 days.
5

Decide whether this environment records replay

Replay is a per-frontend switch in each environment’s KCL, and it reaches the browser as runtime config:
deploy/kcl/prod/main.k
A recording starts only when all of these are true: replay is on, the analytics mode is full, your app has called grantAnalyticsConsent() from @reliantlabs/forge-web-runtime after your consent manager says yes, the browser sends no Global Privacy Control or Do Not Track signal, and the session falls within replay_sample_rate.
New projects scaffold _session_replay = True in every environment, and the forge.BrowserTelemetry default is replay = False. The scaffold records nothing as written, because the default analytics mode is identified, and an identified app never records a replay. Moving to full and granting consent is what starts recording. A site adopted with --in-place scaffolds _session_replay = False.
Masking happens in the browser and cannot be turned off. All text and every input are masked, canvases are not recorded, media and iframes are blocked, and request bodies and headers are not captured (what is masked).
6

Turn replay off for an environment

Set _session_replay = False in that environment’s main.k, commit, and cut a new release. Hosted deploys ship only recorded releases. Promoting that release removes OTEL_REPLAY from the environment’s config.js, and the deploy refuses until you acknowledge the change:
terminal
terminal
Open tabs keep recording until they reload.
7

Verify the change

terminal
OTEL_REPLAY is gone, and new sessions no longer say “replay recorded”. They keep their timeline and their errors, and they drop out of obs sessions.

What this does not do

  • Replay never records unmasked, and no setting unmasks or unblocks selected elements. If a frontend shows data that must never appear in a recording, even masked, keep its replay off.
  • The CLI does not play replays. It prints timelines, and the console plays recordings.
  • A local environment has no sessions. obs sessions and obs session read hosted environments only.
  • Replay records a person. Masking does not replace consent, so describe replay in your privacy notice (privacy and data).

Troubleshooting

The list shows only sessions with a recorded replay, and the scaffold’s identified analytics mode never records one. Open the session from its issue with obs issue <id> <env> --json --fields latest_event.session_id.
A release that drops a config.js key, such as OTEL_REPLAY when you turn replay off, needs --acknowledge-destructive runtime_config_regression --note "<why>". The reason is recorded on the promotion.

Next steps

Find the release that caused an error

Tie the issue to the release and commits that introduced it.

Route alerts to Slack, PagerDuty or email

Get the NewIssue alert for a new frontend error where your team works.

Session timelines and replay

Every timeline entry, the JSON schemas, retention and cost.

Debug production with an AI agent

Hand the same timelines and issues to an agent.