Set Up Session Replay

Session Replay helps you get to the root cause of an error or latency issue faster by providing you with a video-like reproduction of what was happening in the user's browser before, during, and after the issue. Rewind and replay your application's DOM state, key user interactions like mouseclicks and scrolls, network requests, and console entries in a single combined UI inspired by your browser's DevTools.

By default, our Session Replay SDK masks all DOM text content, images, and user input, giving you heightened confidence that no sensitive data leaves the browser. To learn more, see Session Replay Privacy.

Pre-requisites

Install

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

Set Up

// 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,
    }),
  ],
});

myUndefinedFunction();

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

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

Content Security Policy (CSP)

Session Replay uses a WebWorker to perform work (e.g. compression) off the main UI thread so as not to degrade the performance of your application. Add the below entry to make sure that workers can be loaded:

worker-src 'self' blob:

Safari versions <= 15.4 do not support worker-src, you will need to additionally add an entry for child-src:

child-src 'self' blob:

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