> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Session timelines and replay for frontend errors

> See what a user did before a frontend error: browser sessions, text timelines for agents, and replay. Replay is opt-in, masked, and needs consent.

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](#replay-is-opt-in-and-masked).

## 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](https://docs.reliantlabs.io/hosting/observability/dashboards-and-alerts.md#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:

| Entry | What it shows |
| - | - |
| `navigate` | A page the user opened, and the page they came from. |
| `click` | The element the user clicked, as a masked selector. Never the element's text. |
| `request` | A request that failed: method, path, status (or a network failure), and duration. It carries its trace id. |
| `error` | A browser error with its type and message, the page it happened on, and the [issue](https://docs.reliantlabs.io/hosting/observability/dashboards-and-alerts.md#how-errors-are-grouped) it belongs to once the platform has grouped it. It carries its trace id. |
| `event` | A custom event your app recorded with `track(...)`, with its properties. |

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):

```text theme={null}
session 91b955b313a1a86644ea53730a92deab  acme-web 4f2a9c1d03be  user user-42
  2026-11-18T09:41:07Z, 2m10s: 3 pages, 9 interactions, 1 errors, replay recorded (watch it in the console)
  entry /dashboard

+00:00.0  navigate  /dashboard
+00:12.4  click     button #save-draft on /dashboard
+00:12.6  request   POST /api/drafts.v1.DraftService/Save → 500 (412ms)  trace 0af7651916cd43dd8448eb211c80319c
+00:12.7  error     TypeError: Cannot read properties of undefined on /dashboard → issue ISS-7f3a  trace 0af7651916cd43dd8448eb211c80319c
```

## 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:

```bash theme={null}
reliant forge obs issue ISS-7f3a prod --json --fields latest_event.session_id
reliant forge obs session 91b955b313a1a86644ea53730a92deab prod
```

**From a user or a page.** List sessions, newest first, filtered to what you are chasing. The last column is the session id:

```bash theme={null}
reliant forge obs sessions prod --has-error
reliant forge obs sessions prod --user user-42 --since 7d
reliant forge obs sessions prod --path /checkout --has-replay
```

`--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:

```bash theme={null}
reliant forge obs sessions prod --has-error --json --fields sessions.id,sessions.user_id,sessions.errors
reliant forge obs session 91b955b313a1a86644ea53730a92deab prod --json
```

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`](https://docs.reliantlabs.io/hosting/observability/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:

```python theme={null}
_session_replay = True

_web_frontend = forge.Frontend {
    name = "web"
    path = "frontends/web"
    telemetry = forge.BrowserTelemetry {
        replay = _session_replay
        replay_sample_rate = 0.25          # share of sessions, 0.0 to 1.0
        analytics = forge.Analytics {mode = "full"}
    }
}

_bundle = forge.Bundle {
    observability = forge.Observability {}   # a hosted frontend with replay on needs this
}
```

`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.

> [!WARNING]
>
> 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](https://docs.reliantlabs.io/help/privacy.md) 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:

```python theme={null}
observability = forge.Observability {
    retention = forge.ObservabilityRetention {replay_days = 7}
}
```

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](https://docs.reliantlabs.io/hosting/observability-billing.md) has the worked bill. A recording adds browser work and volume, so the sample rate is also your cost control.

## Related topics

* [Hosted dashboards, alerts and issues](https://docs.reliantlabs.io/hosting/observability/dashboards-and-alerts.md) covers how browser errors become issues, and the user, location and device attached to each session.
* [Querying with forge obs](https://docs.reliantlabs.io/hosting/observability/forge-obs.md) lists every `forge obs` command, the JSON contract and exit codes.
* [Where the telemetry goes](https://docs.reliantlabs.io/hosting/observability/where-it-goes.md) covers retention, usage and switching signals off.
* [Observability billing and limits](https://docs.reliantlabs.io/hosting/observability-billing.md) explains what replay and browser telemetry cost.
* [Privacy and data](https://docs.reliantlabs.io/help/privacy.md) describes what is collected from visitors, the analytics modes, and Global Privacy Control and Do Not Track.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.