Configuration

General Integration Configuration

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

The following can be configured as integration options in replayIntegration({}):

Privacy Configuration

We take privacy seriously, so we provide a number of privacy-oriented settings. Learn more about these in our our Session Replay privacy documentation.

If you're working on a static website that's free of personal identifiable or other type of private data, you can opt out of the default text masking and image blocking by configuring the maskAllText and blockAllMedia configuration options respectively:

Sentry.replayIntegration({
  // NOTE: This will disable built-in masking. Only use this if your site has no sensitive data, or if you've already set up other options for masking or blocking relevant data, such as 'ignore', 'block', 'mask' and 'maskFn'.
  maskAllText: false,
  blockAllMedia: false,
});

Starting with v8, the options unblock and unmask do not add default DOM selectors anymore. If you want to keep the default behavior of previous versions, then you should explicitly specify them in your configuration:

Sentry.replayIntegration({
  unblock: [".sentry-unblock, [data-sentry-unblock]"],
  unmask: [".sentry-unmask, [data-sentry-unmask]"],
});

The following is a complete list of options that can be used in replayIntegration({}):

Sampling

To learn more about how session sampling works, check out our Default Session Initialization docs.

Network Details

By default, Replay will capture basic information about all outgoing fetch and XHR requests in your application. This includes the URL, request and response body size, method, and status code. The intention is to limit the chance of collecting private data.

To capture additional information such as request and response headers or bodies, you'll need to opt-in via networkDetailAllowUrls (requires SDK version >= 7.50.0). This will make it possible for you to elect to only add URLs that are safe for capturing bodies and avoid any endpoints that may contain Personal Identifiable Information, (PII).

Any URL matching the given pattern(s) will then be captured with additional details:

replayIntegration({
  networkDetailAllowUrls: [window.location.origin],
});

If you give us a string, we'll match any URL that contains that string. You can use a regex to handle exact or more complex matches.

Requests to a URL matched by the configured patterns will be enhanced with the request and response body, as well as the following default headers:

• Content-Type
• Content-Length
• Accept

If you want to capture additional headers, you'll have to configure them with the options networkRequestHeaders and networkResponseHeaders, for example:

replayIntegration({
  networkDetailAllowUrls: [
    window.location.origin,
    "api.example.com",
    /^https:\/\/api\.example\.com/,
  ],
  networkRequestHeaders: ["Cache-Control"],
  networkResponseHeaders: ["Referrer-Policy"],
});

Identifying Users

You can use the Sentry SDK to link a user to a session. Read more about it in our Identify Users docs.

Sentry.setUser({ email: "jane.doe@example.com" });

Using a Custom Compression Worker

By default, Session Replay will use an inlined web worker script to compress Replay data before sending it over the network. This drastically reduces the amount of data transferred, improving performance and reducing network overhead. Because compressing data is CPU intensive, we use a web worker to offload this work to a separate thread.

While an inlined worker will work well for most applications, there are two main problems with this:

1. Since the worker code is inlined, it increases the main bundle size of your application.
2. Using inline workers can cause CSP violations if your application has a very strict CSP policy. See our CSP docs for more information.

To solve these problems, we provide the ability to use a custom worker script. This allows you to host the worker script on your own domain, and avoid the CSP issues that come with inline workers. Additionally, the worker script can then be removed from the main application bundle and served and cached separately.

Follow these steps in order to use a custom compression worker:

1. Download the example worker script from our Github repository.
2. Host this worker script on the same domain as your application. For example, if your application is hosted at https://example.com, you could host the worker script at https://example.com/assets/worker.min.js.
3. Configure your custom worker script in Replay:

replayIntegration({
  workerUrl: "/assets/worker.min.js",
});

4. You can now Tree Shake the default included worker script. If you are using our bundler plugins (version 2.10.0 or later), you can do:

sentryPlugin({
  // other config
  bundleSizeOptimizations: {
    excludeReplayWorker: true,
  },
});

Since you are hosting this script yourself, you are responsible for keeping it up to date. We recommend that you check for updates to the worker script periodically, and update it as needed. The worker script API is guaranteed to remain stable inside of a major version, so any v7 worker script should be backward and forward compatible with any v7 SDK version. However, we may make improvements or bug fixes to the worker script, which you will miss out on if you don't update it.

Mutation Limits

Session Replay works by recording incremental DOM changes that occur in your web application. Generally, these changes occur in small batches and cause minimal overhead. However, it can be easy to overlook cases that will cause a large amount of DOM mutations to happen in a single update. An example is a custom dropdown component that has an unbounded list of options to render. This can negatively impact performance without Session Replay and its effects will be magnified with Session Replay enabled. In order to avoid this scenario, Session Replay will stop recording if it detects a large number of mutations (default: 10,000), which can be configured by setting mutationLimit. Additionally, we provide breadcrumbs in the replay to warn you when a large number of mutations are detected (default: 750).

replayIntegration({
  mutationBreadcrumbLimit: 1000,
  mutationLimit: 1500,
});

Custom breadcrumbs

Our SDKs allow you to send custom breadcrumbs, which will appear in the Replay Details UI alongside existing breadcrumbs. To learn how to send custom breadcrumbs, read the docs here. Note that any custom breadcrumbs you send will be reflected in both the Issue Details breadcrumbs UI and the Replay Details breadcrumbs tab.

All custom breadcrumbs in the Replay Details will appear grey, and can be identified by the terminal logo.

In Replay Details, the breadcrumb message will take precedence over the data property. If the message property is set, then the string will be displayed like this:

If message is not set, then the breadcrumb will display the data property by default. For example:

The title of the breadcrumb will be the breadcrumb category that you set. If no category is set, then we will use the breadcrumb message. If that doesn't exist, we'll use the description. The last fallback with be a default title of "Custom".