Documentation Grafana Cloud Monitor applications Frontend Observability Session replay How it works

How Session Replay works

Session Replay is an add-on instrumentation for the Grafana Faro Web SDK that records browser interactions in a user’s session and reconstructs them as a recording in Grafana Cloud Frontend Observability.

Architecture overview

The Replay Instrumentation package, @grafana/faro-instrumentation-replay, runs alongside the rest of the Faro Web SDK in the browser. It hooks into the same session lifecycle as your other Faro telemetry and forwards recording events to the same Grafana Cloud Collector endpoint.

Faro Instrumentation Replay package

The @grafana/faro-instrumentation-replay package adds Session Replay to the Faro Web SDK. It captures a lightweight recording of what happens in a user’s browser so you can play a session back as it occurred and view it alongside the logs, errors, traces, and other telemetry Faro already collects for that same session.

It’s responsible for:

• Deciding which sessions to record. Recording happens only for sessions Faro is already sampling, and you can narrow that further with a replay-specific sampling rate. For example, you can collect telemetry for every session but record replays for only 10% of them. The decision is stable for the lifetime of a session, so a given session is recorded consistently across page reloads.
• Applying masking and privacy rules in the browser, before any data is sent. Sensitive content is masked, blocked, or ignored on the user’s device as the recording is captured, so protected data never leaves the browser. By default, all input values and text are masked. You can make masking more selective, exclude specific elements, or transform and drop individual events with a custom filter.
• Pausing during inactivity. After a period with no interaction, recording pauses so idle time isn’t captured, then resumes automatically on the next interaction.

Grafana Cloud Collector endpoint

The Grafana Cloud Collector endpoint receives Session Replay events through the same pipeline as the rest of your Faro telemetry. Events are correlated with your existing logs, errors, traces, and web vitals by session ID, so you can jump from a frontend error or trace directly into the corresponding replay.

What Session Replay captures

Session Replay captures a structured representation of the page and the user’s interactions with it:

• Initial DOM snapshot: A full serialized snapshot of the page’s DOM when recording starts.
• DOM mutations: Incremental changes to the DOM, such as added or removed nodes and attribute or text changes.
• User interactions: Pointer movements, clicks, scrolls, viewport resizes, text input, and selection.
• Lifecycle events: Events that mark when recording started, paused, and resumed within a session.

The following are recorded only when you explicitly enable them through configuration options:

• recordCanvas - Canvas element contents.
• inlineImages - Image content stored in the recording instead of referenced by URL.
• inlineStylesheet - Stylesheet content stored in the recording instead of linked.
• collectFonts - Fonts used by the page.
• recordCrossOriginIframes - Cross-origin iframe contents.

Session Replay focuses on what the user saw and did on the page. Other telemetry signals, such as network requests, console logs, and errors, are captured by the rest of the Faro Web SDK and correlated with the replay by session ID, so you can move between a recording and its related telemetry.

Sampling

Session Replay uses two independent layers of sampling:

1. Faro session sampling decides whether Faro collects telemetry for a given session at all. If a session isn’t sampled by Faro, Session Replay doesn’t record it.
2. Session Replay sub-sampling decides what fraction of Faro-sampled sessions also get a recording, configured through the samplingRate option on ReplayInstrumentation.

The Session Replay sub-sampling decision is deterministic for a given session ID, so a user either has a replay for the entire session or doesn’t, regardless of how many times they reload the page.

For configuration details, refer to Sub-sampling and the Faro sampling documentation.

Privacy by default

Session Replay applies masking on the client-side, before any recording data is sent to Grafana Cloud. By default:

• All input values are masked.
• All text content on the page is masked.

You can configure these settings by using the privacy and masking options. Refer to Data masking for details.

Inactivity pause and resume

To reduce noise, Session Replay automatically pauses recording after a configurable period of user inactivity. Inactivity is defined as the absence of pointer movement, clicks, scrolling, viewport resizes, or text input.

When the user interacts with the page again, Session Replay resumes recording and takes a fresh DOM snapshot so the player has a complete picture of the page at the moment activity resumed.

You can configure or disable this behavior through the inactivityThresholdMs option.

Supported web browsers

Session Replay supports the current version of the following browsers. This applies to sampling and watching user sessions in Grafana Cloud.

• Chrome/Chromium
• Firefox
• Safari
• Microsoft Edge

Typical workflow

A typical Session Replay workflow follows these steps:

1. Instrument your application with the Faro Web SDK and the Faro Instrumentation Replay package.
2. Configure masking, sampling, and other privacy options to match your organization’s requirements.
3. Deploy your application and let Faro collect sessions and recordings.
4. In Grafana Cloud Frontend Observability, browse and filter sessions, or jump into a replay directly from a related error, log, or trace.
5. Use the replay to reproduce and debug frontend issues, and to understand how users move through your application.