@sentry/replay

What is @sentry/replay?

The @sentry/replay package is designed to capture and replay web application interactions to help in debugging and monitoring. It allows developers to record user sessions, including clicks, inputs, and navigation, which can be replayed to understand user behavior or diagnose issues.

What are @sentry/replay's main functionalities?

Session Recording

This feature enables the recording of user sessions, capturing interactions such as clicks, inputs, and page navigation. The code snippet shows how to initialize Sentry with the Replay integration.

Sentry.init({
  dsn: 'YOUR_SENTRY_DSN',
  integrations: [new Sentry.Replay({})]
});

Replay Events

Allows developers to capture and send replay events to Sentry. This can include a series of user interactions that led to an error or an interesting event.

Sentry.captureReplay({
  url: window.location.href,
  interactions: capturedInteractions
});

Other packages similar to @sentry/replay

rrweb

rrweb stands for 'record and replay the web', which is a tool for recording and replaying users' interactions on the web. It offers similar functionalities to @sentry/replay by capturing user sessions and interactions for replay. However, rrweb is more focused on the recording aspect and can be used independently of error tracking systems.

logrocket

LogRocket is a more comprehensive solution that combines session replay, performance monitoring, and error tracking. It offers similar session replay capabilities to @sentry/replay but is part of a larger suite of tools designed for debugging and monitoring web applications. LogRocket provides detailed insights into users' interactions, network requests, and console logs alongside the replay feature.

README

Sentry Session Replay

Pre-requisites

@sentry/replay requires Node 12+, and browsers newer than IE11.

Installation

Replay can be imported from @sentry/browser, or a respective SDK package like @sentry/react or @sentry/vue. You don't need to install anything in order to use Session Replay. The minimum version that includes Replay is 7.27.0.

For details on using Replay when using Sentry via the CDN bundles, see CDN bundle.

Setup

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

import * as Sentry from '@sentry/browser';
// or e.g. import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: '__DSN__',

  // 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
      // See below for all available options
    })
  ],
  // ...
});

Lazy loading Replay

Replay will start automatically when you add the integration. If you do not want to start Replay immediately (e.g. if you want to lazy-load it), you can also use addIntegration to load it later:

import * as Sentry from "@sentry/react";
import { BrowserClient } from "@sentry/browser";

Sentry.init({
  // Do not load it initially
  integrations: []
});

// Sometime later
const { Replay } = await import('@sentry/browser');
const client = Sentry.getCurrentHub().getClient<BrowserClient>();

// Client can be undefined
client?.addIntegration(new Replay());

Identifying Users

If you have only followed the above instructions to setup session replays, you will only see IP addresses in Sentry's UI. In order to associate a user identity to a session replay, use setUser.

import * as Sentry from "@sentry/browser";

Sentry.setUser({ email: "[e-mail]" });

Stopping & starting Replays manually

Replay recording only starts when it is included in the integrations array when calling Sentry.init or calling addIntegration from the a Sentry client instance. To stop recording you can call stop().

import * as Sentry from "@sentry/react";
import { BrowserClient } from "@sentry/browser";

const replay = new Replay();

Sentry.init({
  integrations: [replay]
});

const client = Sentry.getCurrentHub().getClient<BrowserClient>();

// Add replay integration, will start recoring
client?.addIntegration(replay);

// Stop recording
replay.stop();

When both replaysSessionSampleRate and replaysOnErrorSampleRate are 0, recording will not start. In this case, you can manually start recording:

replay.start(); // Will start a session in "session" mode, regardless of sample rates
replay.startBuffering(); // Will start a session in "buffer" mode, regardless of sample rates

Loading Replay as a CDN Bundle

As an alternative to the NPM package, you can use Replay as a CDN bundle. Please refer to the Session Replay installation guide for CDN bundle instructions.

Deprecated Replay integration bundle

Installing the replay integration as a secondary integration bundle to the SDK bundle was deprecated in favour of complete CDN bundles that already contain the replay integration. No need to keep two bundles in sync anymore. The `replay.(min.)js` bundle will be removed in v8 of the JS SDKs.

<script
  src="https://browser.sentry-cdn.com/7.41.0/bundle.min.js"
  crossorigin="anonymous"
></script>
<script
  src="https://browser.sentry-cdn.com/7.41.0/replay.min.js"
  crossorigin="anonymous"
></script>

Sessions

A 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 30 minutes have elapsed. Closing the browser tab will end the session immediately according to the rules for SessionStorage.

Accessing the Replay Session ID

You can get the ID of the currently running session via replay.getReplayId(). This will return undefined if no session is ongoing.

Replay Captures Only on Errors

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 more relevant to your interests:

• replaysSessionSampleRate - The sample rate for replays that begin recording immediately and last the entirety of the user's session.
• 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.

When Replay is initialized, we check the replaysSessionSampleRate. If it is sampled, then we start recording & sending Replay data immediately. Else, if replaysOnErrorSampleRate > 0, we'll start recording in buffering mode. In this mode, whenever an error occurs we'll check replaysOnErrorSampleRate. If it is sampled, when we'll upload the Replay to Sentry and continue recording normally.

Configuration

SDK Configuration

The following options can be configured on the root level of your browser-based Sentry SDK, in init({}):

key	type	default	description
replaysSessionSampleRate	number	0	The sample rate for replays that begin recording immediately and last the entirety of the user's session. 1.0 will collect all replays, 0 will collect no replays.
replaysOnErrorSampleRate	number	0	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. 1.0 capturing all sessions with an error, and 0 capturing none.

General Integration Configuration

The following options can be configured as options to the integration, in new Replay({}):

key	type	default	description
stickySession	boolean	true	Keep track of the user across page loads. Note a single user using multiple tabs will result in multiple sessions. Closing a tab will result in the session being closed as well.

Privacy Configuration

The following options can be configured as options to the integration, in new Replay({}):

key	type	default	description
maskAllText	boolean	true	Mask all text content. Will pass text content through maskTextFn before sending to server.
maskAllInputs	boolean	true	Mask values of <input> elements. Passes input values through maskInputFn before sending to server.
blockAllMedia	boolean	true	Block all media elements (img, svg, video, object, picture, embed, map, audio)
maskTextFn	(text: string) => string	(text) => '*'.repeat(text.length)	Function to customize how text content is masked before sending to server. By default, masks text with *.
block	Array	.sentry-block, [data-sentry-block]	Redact any elements that match the DOM selectors. See privacy section for an example.
unblock	Array	.sentry-unblock, [data-sentry-unblock]	Do not redact any elements that match the DOM selectors. Useful when using blockAllMedia. See privacy section for an example.
mask	Array	.sentry-mask, [data-sentry-mask]	Mask all elements that match the given DOM selectors. See privacy section for an example.
unmask	Array	.sentry-unmask, [data-sentry-unmask]	Unmask all elements that match the given DOM selectors. Useful when using maskAllText. See privacy section for an example.
ignore	Array	.sentry-ignore, [data-sentry-ignore]	Ignores all events on the matching input fields. See privacy section for an example.

Deprecated options

In order to streamline our privacy options, the following have been deprecated in favor for the respective options above.

deprecated key	replaced by	description
maskInputOptions	mask	Use CSS selectors in mask in order to mask all inputs of a certain type. For example, input[type="address"]
blockSelector	block	The selector(s) can be moved directly in the block array.
blockClass	block	Convert the class name to a CSS selector and add to block array. For example, first-name becomes .first-name. Regexes can be moved as-is.
maskClass	mask	Convert the class name to a CSS selector and add to mask array. For example, first-name becomes .first-name. Regexes can be moved as-is.
maskSelector	mask	The selector(s) can be moved directly in the mask array.
ignoreClass	ignore	Convert the class name to a CSS selector and add to ignore array. For example, first-name becomes .first-name. Regexes can be moved as-is.

Privacy

There are several ways to deal with PII. By default, the integration will mask all text content with * and block all media elements (img, svg, video, object, picture, embed, map, audio). This can be disabled by setting maskAllText to false. It is also possible to add the following CSS classes to specific DOM elements to prevent recording its contents: sentry-block, sentry-ignore, and sentry-mask. The following sections will show examples of how content is handled by the differing methods.

Masking

Masking replaces the text content with something else. The default masking behavior is to replace each character with a *. In this example the relevant html code is: <table class="sentry-mask">...</table>.

Blocking

Blocking replaces the element with a placeholder that has the same dimensions. The recording will show an empty space where the content was. In this example the relevant html code is: <table data-sentry-block>...</table>.

Ignoring

Ignoring only applies to form inputs. Events will be ignored on the input element so that the replay does not show what occurs inside of the input. In the below example, notice how the results in the table below the input changes, but no text is visible in the input.

https://user-images.githubusercontent.com/79684/192815134-a6451c3f-d3cb-455f-a699-7c3fe04d0a2e.mov

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/replays. However, please note that it is possible that the error count reported on the Replay Detail page does not match the actual errors that have been captured. The reason for that is that errors can be lost, e.g. a network request fails, or similar. This should not happen to often, but be aware that it is theoretically possible.

Manually sending replay data

You can use replay.flush() to immediately send all currently captured replay data. When Replay is currently in buffering mode, this will send up to the last 60 seconds of replay data, and also continue sending afterwards, similar to when an error happens & is recorded.

Footnotes

1. An 'interaction' refers to either a mouse click or a browser navigation event. ↩