@sentry-internal/replay
Advanced tools
This is an internal package that is being re-exported in @sentry/browser and other browser-related SDKs like
@sentry/react or @sentry/vue.
@sentry-internal/replay requires Node 14+, and browsers newer than IE11.
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.
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: [
Sentry.replayIntegration({
// Additional SDK configuration goes in here, for example:
maskAllText: true,
blockAllMedia: true,
// See below for all available options
}),
],
// ...
});
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.getClient<BrowserClient>();
// Client can be undefined
client?.addIntegration(Sentry.replayIntegration());
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' });
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 = Sentry.replayIntegration();
Sentry.init({
integrations: [replay]
});
const client = Sentry.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
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.
<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>
A session starts when the Session Replay SDK is first loaded and initialized. The session will continue until 5 minutes passes without any user interactions1 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.
You can get the ID of the currently running session via replay.getReplayId(). This will return undefined if no
session is ongoing.
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 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.
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. |
The following options can be configured as options to the integration, in Sentry.replayIntegration({}):
| 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. |
The following options can be configured as options to the integration, in Sentry.replayIntegration({}):
| key | type | default | description |
|---|---|---|---|
| maskAllText | boolean | true | Mask all text content. Will pass text content through maskFn 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) |
| maskFn | (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 | [] | 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 | [] | 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. |
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 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 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 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
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.
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.
An 'interaction' refers to either a mouse click or a browser navigation event. ↩
8.0.0
The Sentry JS SDK team is proud to announce the release of version 8.0.0 of Sentry's JavaScript SDKs - it's been a
long time coming! Thanks to everyone for your patience and a special shout out to the brave souls testing preview builds
and reporting issues - we appreciate your support!
We recommend reading the migration guide docs to find out how to address any breaking changes in your code for your specific platform or framework.
To automate upgrading to v8 as much as possible, use our migration codemod @sentry/migr8:
npx @sentry/migr8@latest
All deprecations from the v7 cycle, with the exception of getCurrentHub(), have been removed and can no longer be used
in v8. If you have an advanced Sentry SDK setup, we additionally recommend reading the
in-depth migration guide in our repo which highlights all changes with additional details and
information.
The rest of this changelog highlights the most important (breaking) changes and links to more detailed information.
With v8, we dropped support for several old runtimes and browsers
Node SDKs: The Sentry JavaScript SDK v8 now supports Node.js 14.8.0 or higher. This applies to @sentry/node
and all of our node-based server-side sdks (@sentry/nextjs, @sentry/remix, etc.). Furthermore, version 8 now ships
with full support for ESM-based node apps using Node.js 18.19.0 or higher.
Browser SDKs: The browser SDKs now require ES2018+ compatible browsers. New minimum browser versions:
For more details, please see the version support section in our migration guide.
In v8, we support a lot more node-based packages than before. In order to ensure auto-instrumentation works, the SDK now needs to be imported and initialized before any other import in your code.
We recommend creating a new file (e.g. instrumentation.js) to import and initialize the SDK. Then, import the file on
top of your entry file or detailed instructions, check our updated SDK setup docs
initializing the SDK in v8.
The API around performance monitoring and tracing has been streamlined, and we've added support for more integrations out of the box.
Integrations are now simple functions instead of classes. Class-based integrations have been removed:
// old (v7)
Sentry.init({
integrations: [new Sentry.BrowserTracing()],
});
// new (v8)
Sentry.init({
integrations: [Sentry.browserTracingIntegration()],
});
The following packages have been removed or replaced and will no longer be published:
FAQs
User replays for Sentry
The npm package @sentry-internal/replay receives a total of 1,095,634 weekly downloads. As such, @sentry-internal/replay popularity was classified as popular.
We found that @sentry-internal/replay demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 9 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team uncovered a malicious Python package typosquatting the popular 'fabric' SSH library, silently exfiltrating AWS credentials from unsuspecting developers.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.