Initial Session Replay SDK Docs #5899
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| <Note> | ||
|
|
||
| Session Replay is currently in beta. Beta features are still in-progress and may have bugs. We recognize the irony. If you have any questions or feedback, please email us at [[email protected]](mailto:[email protected]). | ||
|
|
||
| </Note> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| Install the Replay package with NPM or your favourite package manager. Alternatively, you can load the Replay integration via a CDN bundle. | ||
|
|
||
| ```bash {tabTitle: ESM} | ||
| # Make sure to have @sentry/browser or a Framework SDK (e.g. @sentry/react) installed | ||
|
|
||
| # Using yarn | ||
| yarn add @sentry/replay | ||
|
|
||
| # Using npm | ||
| npm install --save @sentry/replay | ||
| ``` | ||
|
|
||
| ```html {tabTitle: CDN} | ||
| <!-- | ||
| Note that the Replay bundle only contains the Replay integration and not the | ||
| entire Sentry SDK. You have to add it in addition to the Sentry Browser SDK bundle: | ||
| --> | ||
|
|
||
| <script | ||
| src="https://browser.sentry-cdn.com/{{ packages.version('sentry.javascript.browser') }}/bundle.min.js" | ||
| integrity="sha384-{{ packages.checksum('sentry.javascript.browser', 'bundle.min.js', 'sha384-base64') }}" | ||
| crossorigin="anonymous" | ||
| ></script> | ||
|
|
||
| <script | ||
| src="https://browser.sentry-cdn.com/{{ packages.version('sentry.javascript.browser') }}/replay.min.js" | ||
| integrity="sha384-{{ packages.checksum('sentry.javascript.browser', 'replay.min.js', 'sha384-base64') }}" | ||
| crossorigin="anonymous" | ||
| ></script> | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,54 @@ | ||
| 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 sections](/platforms/javascript/session-replay/custom-instrumentation/) for more details. | ||
|
|
||
| ```javascript {tabTitle: ESM} | ||
| // import Sentry from your framework SDK (e.g. @sentry/react) instead of @sentry/browser | ||
| import * as Sentry from "@sentry/browser"; | ||
|
|
||
| import { Replay } from "@sentry/replay"; | ||
|
|
||
| Sentry.init({ | ||
| dsn: "___PUBLIC_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 Replay({ | ||
| // Additional SDK configuration goes in here, for example: | ||
| maskAllText: true, | ||
| blockAllMedia: true | ||
| // See below for all available options | ||
| }) | ||
| ], | ||
| // ... | ||
| }); | ||
| ``` | ||
|
|
||
| ```javascript {tabTitle: CDN} | ||
| Sentry.init({ | ||
| dsn: "___PUBLIC_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.Integrations.Replay({ | ||
| // Additional SDK configuration goes in here, for example: | ||
| maskAllText: true, | ||
| blockAllMedia: true | ||
| // See below for all available options | ||
| }) | ||
| ], | ||
| // ... | ||
| }); | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| --- | ||
| title: General Configuration | ||
| sidebar_order: 410 | ||
| supported: | ||
| - javascript | ||
| - javascript.angular | ||
| - javascript.ember | ||
| - javascript.gatsby | ||
| - javascript.nextjs | ||
| - javascript.react | ||
| - javascript.remix | ||
| - javascript.svelte | ||
| - javascript.vue | ||
| notSupported: | ||
| - javascript.capacitor | ||
| - javascript.cordova | ||
| - javascript.electron | ||
| - javascript.wasm | ||
| description: "Learn about the general Session Replay configuration fields." | ||
| --- | ||
|
|
||
| <Include name="beta-note-session-replay.mdx" /> | ||
|
|
||
| ## 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](/platforms/javascript/enriching-events/identify-user/). | ||
|
|
||
| ```javascript | ||
| import * as Sentry from "@sentry/browser"; | ||
| Sentry.setUser({ email: "[email protected]" }); | ||
| ``` | ||
|
|
||
| ## 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(). | ||
|
|
||
| ```javascript {tabTitle: ESM} | ||
| const replay = new Replay(); // This will *NOT* begin recording replays | ||
|
|
||
| replay.start(); // Start recording | ||
|
|
||
| replay.stop(); // Stop recording | ||
| ``` | ||
|
|
||
| ```javascript {tabTitle: CDN} | ||
| const replay = new Sentry.Integrations.Replay(); // This will *NOT* begin recording replays | ||
|
|
||
| replay.start(); // Start recording | ||
|
|
||
| replay.stop(); // Stop recording | ||
| ``` | ||
|
|
||
| ## General Integration 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.1` | 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 | `1.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 `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. | | ||
|
|
||
| ## Optimization Configuration | ||
|
|
||
| The following options can be configured as options to the integration, in `new Replay({})`: | ||
|
|
||
| | 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 | | ||
|
|
||
| ## rrweb Configuration | ||
|
|
||
| In addition to the options described above, you can also directly pass configuration to [rrweb](https://github.com/rrweb-io/rrweb/blob/rrweb%401.1.3/guide.md), which is the underlying library used to make the recordings: | ||
|
|
||
| ```javascript | ||
| new Replay({ | ||
| // any further configuration here is passed directly to rrweb | ||
| }); | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| --- | ||
| title: Custom Instrumentation | ||
|
Member
There was a problem hiding this comment. nit (feel free to ignore): Is "Custom Instrumentation" the correct title here? To me, the content here seems to be more around additional advanced configuration than doing custom things (maybe apart from the manual
Member
Author
|
||
| sidebar_order: 4100 | ||
| supported: | ||
| - javascript | ||
| - javascript.angular | ||
| - javascript.ember | ||
| - javascript.gatsby | ||
| - javascript.nextjs | ||
| - javascript.react | ||
| - javascript.remix | ||
| - javascript.svelte | ||
| - javascript.vue | ||
| notSupported: | ||
| - javascript.capacitor | ||
| - javascript.cordova | ||
| - javascript.electron | ||
| - javascript.wasm | ||
| description: "Learn how to set up General and Privacy aware configuration fields." | ||
| --- | ||
|
|
||
| <Include name="beta-note-session-replay.mdx" /> | ||
|
|
||
| <PageGrid /> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| --- | ||
| title: Privacy Configuration | ||
| sidebar_order: 4200 | ||
| supported: | ||
| - javascript | ||
| - javascript.angular | ||
| - javascript.ember | ||
| - javascript.gatsby | ||
| - javascript.nextjs | ||
| - javascript.react | ||
| - javascript.remix | ||
| - javascript.svelte | ||
| - javascript.vue | ||
| notSupported: | ||
| - javascript.capacitor | ||
| - javascript.cordova | ||
| - javascript.electron | ||
| - javascript.wasm | ||
| description: "Configuring Session Replay to maintain user and data privacy." | ||
| --- | ||
|
|
||
| <Include name="beta-note-session-replay.mdx" /> | ||
|
|
||
| There are several ways to deal with PII (personally identifiable information). 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. | ||
|
|
||
|  | ||
|
|
||
| ### 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. | | ||
| | 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. <br /> 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 [Blocking](#blocking) above for an example. | | ||
| | blockSelector | string | `'[data-sentry-block]'` | Redact all elements that match the DOM selector. See [Blocking](#blocking) above for an example. | | ||
| | ignoreClass | string \| RegExp | `'sentry-ignore'` | Ignores all events on the matching input field. See [Ignoring](#ignoring) above for an example. | | ||
| | maskTextClass | string \| RegExp | `'sentry-mask'` | Mask all elements that match the class name. See [Masking](#masking) above for an example. | | ||
| | maskTextSelector | string | `undefined` | Mask all elements that match the given DOM selector. See [Masking](#masking) above for an example. | |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,77 @@ | ||
| --- | ||
| title: Set Up Session Replay | ||
| sidebar_order: 4000 | ||
| supported: | ||
| - javascript | ||
| - javascript.angular | ||
| - javascript.ember | ||
| - javascript.gatsby | ||
| - javascript.nextjs | ||
| - javascript.react | ||
| - javascript.remix | ||
| - javascript.svelte | ||
| - javascript.vue | ||
| notSupported: | ||
| - javascript.capacitor | ||
| - javascript.cordova | ||
| - javascript.electron | ||
| - javascript.wasm | ||
| description: "Learn how to enable Session Replay in your app if it is not already set up." | ||
| --- | ||
|
|
||
| <Include name="beta-note-session-replay.mdx" /> | ||
|
|
||
| With [session replays](/product/session-replay/) you can get to the root cause of an error or latency issue faster by seeing all the technical details related to that issue in one visual replay on your web application. Sentry provides a video-like reproduction of user interactions on a site or web app. All user interactions - including page visits, mouse movements, clicks, and scrolls - are captured, helping developers connect the dots between a known issue and how a user experienced it in the UI. | ||
|
|
||
| ## Pre-requisites | ||
|
|
||
| For the sentry-replay integration to work, you must have the [Sentry browser SDK package](https://www.npmjs.com/package/@sentry/browser), or an equivalent framework SDK (e.g. [@sentry/react](https://www.npmjs.com/package/@sentry/react)) installed. The minimum version required for the SDK is `7.24.0`. | ||
|
|
||
| Make sure to use the exact same version of `@sentry/replay` as your other Sentry package(s), e.g. `@sentry/browser` or `@sentry/react`. | ||
|
|
||
| `@sentry/replay` requires Node 12+, and browsers newer than IE11. | ||
|
|
||
| ## Installation | ||
|
|
||
| <PlatformContent includePath="session-replay/install-session-replay" /> | ||
|
|
||
| ## Set up | ||
|
|
||
| <PlatformContent includePath="session-replay/setup-session-replay" /> | ||
|
|
||
| ## 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](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage). | ||
|
|
||
| <Note> | ||
|
|
||
| An 'interaction' refers to either a mouse click or a browser navigation event. | ||
|
|
||
| </Note> | ||
|
|
||
| ### 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](#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: | ||
|
|
||
| 1. <PlatformIdentifier name="replays-session-sample-rate" /> - The sample rate for replays that begin recording immediately and last the entirety of the user's session. | ||
| 2. <PlatformIdentifier name="replays-on-error-sample-rate" /> - 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. <PlatformIdentifier name="replays-session-sample-rate" /> is evaluated first. If it is sampled, then the replay recording begins. Otherwise, <PlatformIdentifier name="replays-on-error-sample-rate" /> 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/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. | ||
|
|
||
| ## Verify | ||
|
|
||
| While you're testing, set <PlatformIdentifier name="replays-session-sample-rate" /> 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 <PlatformIdentifier name="replays-on-error-sample-rate" /> set to `1.0`. | ||
|
|
||
| **Next Steps:** | ||
|
|
||
| <PageGrid /> |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
SDK nav:
(the exclude list above means that the link will not appear (again) under the "Sentry for JavaScript" heading)