Skip to main content
A frontend error report tells you what broke. It rarely tells you what the user did to get there: which page they came from, what they clicked, which request failed a moment before. Forge records that as a session for every hosted frontend, and you can read it as a text timeline from the terminal, as a list in the console, or, if you opt in, as a masked replay of the page. The timeline needs no setup beyond the browser telemetry forge already scaffolds. Replay is a separate, opt-in switch, covered below.

What a session is

A session is one visit to a frontend. The browser SDK assigns it an id and ends it after 15 minutes without activity, or after 4 hours. Every request the frontend makes carries that id, which your forge services record on their side, so a session links to the backend traces it caused and a trace links back to its session. Below the full analytics tier (the default) nothing is stored on the device, so the session id lives in memory and holds while the page is open. See Who and where for how users, location and device are attached to a session. Sessions are derived by the platform from browser telemetry, so they exist for hosted environments. A local environment has no session tables and answers “could not look”.

What the timeline records

forge obs session <id> <env> prints one session oldest first, each entry stamped with the time since the session started. It records five kinds of entry: Paths have their query string and fragment cut, so an email, token or search term in a URL never appears. The timeline prints no recording bytes: the replay itself is for the console’s player. The output looks like this (illustrative values, real layout):

Find the session for an error or a user

There are two ways in, and both end at the same command. From an issue. An issue’s latest event carries the id of the session it happened in. Read it from the issue, then open that session:
From a user or a page. List sessions, newest first, filtered to what you are chasing. The last column is the session id:
--user matches the id your frontend passed to setTelemetryUser(id), or the opaque id an auth adapter from @reliantlabs/forge-web-runtime attached; pass an internal id, never an email. --path matches the session’s entry path, case-insensitively. --since defaults to 24 hours and reaches back at most 30 days. Other filters are --service, --limit and --page-token. Each row shows the frontend, start time, user, entry path, length, page views, interactions, browser errors, whether a replay was recorded, and the id. From a timeline, the next step is usually reliant forge obs trace <trace-id> prod on a failed request or an error, which shows the backend side of the same request. The command prints the suggested next commands itself.

For agents

Both commands take --json and print one document, with progress on stderr:
The schemas are forge.obs.sessions/v1 and forge.obs.session/v1. --fields keeps only the dotted paths you name, and the document’s suggested array holds the follow-up commands. Timeline entries carry kind, offset_ms, trace_id, span_id and, for errors, issue_id and fingerprint. obs session exits 0 when the session is found, 1 for a bad id or a session the environment does not have, and 2 when it could not be looked up. A long timeline continues with --page-token. Sessions are kept for 30 days, and the CLI reads a hosted timeline over at most 7 days of that range. Reads are scoped to your organization: a member of it, or a machine credential that acts for it and carries obs:read. See forge obs for the rest of the command family.

Replay is opt-in and masked

Replay records what a user’s browser displayed, so forge treats it as the one telemetry category that is off until you turn it on. The timeline above does not depend on it: a session without a recording still has its navigations, clicks, failed requests and errors. Nothing records until all of these are true:
  1. The frontend declares replay = True in the environment, which opts the environment’s observability policy in.
  2. The app is in the full analytics tier: analytics.mode = "full" for the environment, and the app has called grantAnalyticsConsent() from @reliantlabs/forge-web-runtime once its consent manager says yes.
  3. The visitor’s browser does not send Global Privacy Control or Do Not Track.
  4. The session is picked by the sample rate.
The switch lives in the environment’s KCL, per frontend, and reaches the browser as runtime config, so one build promotes across environments and each sets its own, with no rebuild:
forge env render refuses a hosted frontend that sets replay = True in an environment that declares no observability. Setting only the OTEL_REPLAY runtime config key cannot authorize hosted ingestion. To stop recording, set replay = False (or _session_replay = False) and deploy the environment, then reload open tabs. Turning browser telemetry off, or signals = forge.ObservabilitySignals {browser = False}, stops it too.
Do not assume a project records anything. A new forge project with a frontend scaffolds _session_replay = True in each environment’s main.k, but the default analytics mode is identified, which never records a replay until you move to full and grant consent. A project adopted from an existing app keeps replay off. Read your main.k and your consent code to know what your users’ browsers do.
The build variables VITE_OTEL_REPLAY and NEXT_PUBLIC_OTEL_REPLAY, and the environment-wide signals = forge.ObservabilitySignals {replay = True}, are deprecated. They still work in version 1. A build variable exported only at build time makes the page warn once in the console, naming the field to move to.

What is masked

Masking happens in the browser, before anything is sent. The server never unmasks a recording and never alters its bytes. It is forced, not configurable:
  • All text and every input are masked.
  • Canvases are never recorded.
  • Images, pictures, video, audio, iframes, objects and embeds are blocked, images are not inlined, and fonts are not collected.
  • Request and response bodies and headers are not captured.
  • The page URL inside the recording has its query string and fragment removed.
Forge has no setting that records unmasked, and documents none that unmasks or blocks selected elements. The controls you have are coarse: keep replay off for a frontend that shows data you cannot have on a screen recording, or lower replay_sample_rate. Masking is a second layer of protection, not a substitute for consent where your product needs it. Replay records a person, so say so in your privacy notice; Privacy and data describes what Reliant collects and how analytics modes and Global Privacy Control and Do Not Track are handled.

Watching a replay

forge obs sessions --has-replay finds sessions with a recording, and obs session tells you when one exists (“watch it in the console”). The CLI never prints recording bytes. The console’s Sessions view plays the replay, and a trace or an error opens its session and its replay when it has one. When you run forge env up against hosted dev telemetry, forge prints [up] session recording: masked, subject to DNT/GPC, consent and sampling when the server has granted recording, and says it is unavailable when it has not.

Retention and cost

Session replays are kept for 14 days by default, shorter than other browser data because they are the heaviest and most sensitive. You can set the period per environment, from 1 to 30 days:
Replay bytes count against your organization’s monthly observability ingestion, under logs, and browser telemetry as a whole, replay included, has a billing ceiling of 2 GiB per organization per month. Observability billing and limits has the worked bill. A recording adds browser work and volume, so the sample rate is also your cost control.