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 thefull 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:--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:
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:- The frontend declares
replay = Truein the environment, which opts the environment’s observability policy in. - The app is in the
fullanalytics tier:analytics.mode = "full"for the environment, and the app has calledgrantAnalyticsConsent()from@reliantlabs/forge-web-runtimeonce its consent manager says yes. - The visitor’s browser does not send Global Privacy Control or Do Not Track.
- The session is picked by the sample rate.
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.
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.
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:Related topics
- Hosted dashboards, alerts and issues covers how browser errors become issues, and the user, location and device attached to each session.
- Querying with forge obs lists every
forge obscommand, the JSON contract and exit codes. - Where the telemetry goes covers retention, usage and switching signals off.
- Observability billing and limits explains what replay and browser telemetry cost.
- Privacy and data describes what is collected from visitors, the analytics modes, and Global Privacy Control and Do Not Track.