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:readin the organization (credentials).
TypeError for a cart with no coupon.
1
Find the error
terminal
2
Read the source-mapped stack
terminal
3
Open the session the error happened in
The issue’s latest event carries its session id:The user landed on
terminal
/, 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
--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:A recording starts only when all of these are true:
deploy/kcl/prod/main.k
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.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 Open tabs keep recording until they reload.
_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
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 sessionsandobs sessionread hosted environments only. - Replay records a person. Masking does not replace consent, so describe replay in your privacy notice (privacy and data).
Troubleshooting
obs sessions lists nothing, but obs issues shows browser errors
obs sessions lists nothing, but obs issues shows browser errors
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.promote refused (runtime_config_regression)
promote refused (runtime_config_regression)
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.