Set Up Session Replay

With session replays you can get to the root cause of an error or latency issue faster by seeing all the technical details related to that issue in one visual replay on your web application. Sentry provides a video-like reproduction of user interactions on a site or web app. All user interactions — including page visits, mouse movements, clicks, and scrolls — are captured, helping developers connect the dots between a known issue and how a user experienced it in the UI.

By default, it'll mask all fields, so no personally identifiable information (PII) is collected, eliminating any concerns with General Data Protection Regulation (GDPR). Learn more on Session Replay Privacy.

Pre-requisites

For the sentry-replay integration to work, you must have the Sentry browser SDK package, or an equivalent framework SDK (for example, @sentry/react) installed. The minimum version required for the SDK is 7.27.0. If you're on an older version of the SDK, please check the migration document.

Session Replay requires Node 12+, and browsers newer than IE11.

Install

The Replay integration is already included in your browser or framework SDK NPM packages. If you're using CDN bundles instead of NPM packages, you need to load the Replay integration CDN bundle in addition to your browser bundle:

Copied
# Make sure to have @sentry/browser or a Framework SDK (e.g. @sentry/react) installed
npm install --save @sentry/browser

Set Up

To set up the integration, add the following to your Sentry initialization. Several options are supported and passable using the integration constructor. See the configuration documentation for more details.

Copied
// import Sentry from your framework SDK (e.g. @sentry/react) instead of @sentry/browser
import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  // This sets the sample rate to be 10%. You may want this to be 100% while
  // in development and sample at a lower rate in production
  replaysSessionSampleRate: 0.1,

  // If the entire session is not sampled, use the below sample rate to sample
  // sessions when an error occurs.
  replaysOnErrorSampleRate: 1.0,

  integrations: [
    new Sentry.Replay({
      // Additional SDK configuration goes in here, for example:
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],
});

With the settings above, session replays with errors are always captured. You can verify that with the following:

Copied
myUndefinedFunction();

Lazy-loading Replay

Once you've added the integration, Replay will start automatically. If you don't want to start it immediately (lazy-load it), you can use addIntegration:

Copied
Sentry.init({
  // Note, Replay is NOT instantiated below:
  integrations: []
});

// Sometime later
const { Replay } = await import('@sentry/browser');
getCurrentHub().getClient().addIntegration(new Replay());

User Session

A user session starts when the Session Replay SDK is first loaded and initialized. The session will continue until 5 minutes passes without any user interactions with the application or until a maximum of 60 minutes have elapsed. Closing the browser tab will end the session immediately according to the rules for SessionStorage.

Replay Captures on Errors Only

Alternatively, rather than recording an entire session, you can capture a replay only when an error occurs. In this case, the integration will buffer up to one minute worth of events prior to the error being thrown. It will continue to record the session following the rules above regarding session life and activity. Read the sampling section for configuration options.

Sampling

Sampling allows you to control how much of your website's traffic will result in a session replay. There are two sample rates you can adjust to get the replays relevant to your interests:

  1. replaysSessionSampleRate - The sample rate for replays that begin recording immediately and last the entirety of the user's session.
  2. replaysOnErrorSampleRate - The sample rate for replays that are recorded when an error happens. This type of replay will record up to a minute of events prior to the error and continue recording until the session ends.

Sampling occurs when the session is first started. replaysSessionSampleRate is evaluated first. If it is sampled, then the replay recording begins. Otherwise, replaysOnErrorSampleRate is evaluated and if it is sampled, the integration will begin buffering the replay and will only upload a replay to Sentry when an error occurs. The remainder of the replay will behave similarly to a whole-session replay.

Error Linking

Currently, errors that happen on the page while a replay is running are linked to the Replay, making it as easy as possible to jump between related issues and replays. However, it is possible that the error count reported on the Replays Details page does not match the actual errors that have been captured. This is because errors can be lost; for example, a network request may fail or similar. This shouldn't happen often, but it's theoretically possible.

Verify

While you're testing, set replaysSessionSampleRate to 1.0, as that ensures that every user session will be sent to Sentry.

Once testing is complete, we recommend lowering this value in production. We still recommend keeping replaysOnErrorSampleRate set to 1.0.

Next Steps

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").