Package Exports

@sentry/replay
@sentry/replay/dist/index.es.js
@sentry/replay/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@sentry/replay) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

sentry-replay

Note: Session Replay is currently in beta.

Pre-requisites

For the sentry-replay integration to work, you must have the Sentry browser SDK package (minimum version 7.x), or an equivalent framework SDK (e.g. @sentry/react) installed.

Installation

with npm:

npm install --save @sentry/browser @sentry/replay

with yarn:

yarn add @sentry/browser @sentry/replay

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';
import { Replay } from '@sentry/replay';

Sentry.init({
  dsn: '__DSN__',
  integrations: [
    new Replay({
      // 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
      sessionSampleRate: 0.1,

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

      // Mask all text content with asterisks (*). Passes text
      // content through to `maskTextFn` before sending to server.
      //
      // Defaults to true, uncomment to change
      // maskAllText: true,

      // Block all media elements (img, svg, video, object,
      // picture, embed, map, audio)
      //
      // Defaults to true, uncomment to change
      // blockAllMedia: true,
    })
  ],
  // ...
});

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: "jane.doe@example.com" });

Start and Stop Recording

Replay recording only starts automatically when it is included in the integrations key when calling Sentry.init. Otherwise you can initialize the plugin and manually call the start() method on the integration instance. To stop recording you can call the stop().

const replay = new Replay(); // This will *NOT* begin recording replays

replay.start(); // Start recording

replay.stop(); // Stop recording

Configuration

General Configuration

key	type	default	description
sessionSampleRate	number	`0.1`	The sample rate for all sessions, which will capture the entirety from when a user begins a session until the session ends. (1.0 will collect all replays, 0 will collect no replays)
errorSampleRate	number	`1.0`	If a session isn't already being recorded via `sessionSampleRate`, based on `errorSampleRate` the SDK will send the captured replay when an error occurs. (1.0 capturing all sessions with an error, and 0 capturing none).
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

key	type	default	description
maskAllText	boolean	`true`	Mask all text content. Will pass text content through `maskTextFn` 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 `*`.
maskAllInputs	boolean	`true`	Mask values of `<input>` elements. Passes input values through `maskInputFn` before sending to server.
maskInputOptions	Record<string, boolean>	`{ password: true }`	Customize which inputs `type` to mask. Available `<input>` types: `color, date, datetime-local, email, month, number, range, search, tel, text, time, url, week, textarea, select, password`.
maskInputFn	(text: string) => string	`(text) => '*'.repeat(text.length)`	Function to customize how form input values are masked before sending to server. By default, masks values with `*`.
blockClass	string \| RegExp	`'sentry-block'`	Redact all elements that match the class name. See privacy section for an example.
blockSelector	string	`'[data-sentry-block]'`	Redact all elements that match the DOM selector. See privacy section for an example.
ignoreClass	string \| RegExp	`'sentry-ignore'`	Ignores all events on the matching input field. See privacy section for an example.
maskTextClass	string \| RegExp	`'sentry-mask'`	Mask all elements that match the class name. See privacy section for an example.

Optimization Configuration

key	type	default	description
collectFonts	boolean	`false`	Should collect fonts used on the website
inlineImages	boolean	`false`	Should inline `<image>` content
inlineStylesheet	boolean	`true`	Should inline stylesheets used in the recording
recordCanvas	boolean	`false`	Should record `<canvas>` elements
slimDOMOptions	Record<string, boolean>	`{}`	Remove unnecessary parts of the DOM Available keys: `script, comment, headFavicon, headWhitespace, headMetaDescKeywords, headMetaSocial, headMetaRobots, headMetaHttpEquiv, headMetaAuthorship, headMetaVerification`

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>. Masking example

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>. Blocking example

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