Skip to content

Commit bd7347a

Browse files
ryan953Lms24
ryan953
and
Lms24
authored
Initial Session Replay SDK Docs (#5899)
Skeleton of the SDK related files we need for Session Replay Co-authored-by: Lukas Stracke <[email protected]>
1 parent b72ef09 commit bd7347a

File tree

11 files changed

+342
-0
lines changed

11 files changed

+342
-0
lines changed

‎src/components/platformSidebar.tsx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ export const PlatformSidebar = ({
7979
`/${pathRoot}/enriching-events/`,
8080
`/${pathRoot}/data-management/`,
8181
`/${pathRoot}/performance/`,
82+
`/${pathRoot}/session-replay/`,
8283
`/${pathRoot}/profiling/`,
8384
`/${pathRoot}/guides/`,
8485
]}
@@ -90,6 +91,15 @@ export const PlatformSidebar = ({
9091
suppressMissing
9192
tree={tree}
9293
/>
94+
<DynamicNav
95+
root={`/${pathRoot}/session-replay`}
96+
title="Session Replay"
97+
prependLinks={[
98+
[`/${pathRoot}/session-replay/`, "Set Up Session Replay"],
99+
]}
100+
suppressMissing
101+
tree={tree}
102+
/>
93103
<DynamicNav
94104
root={`/${pathRoot}/profiling`}
95105
title="Profiling"

‎src/includes/beta-note-session-replay.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<Note>
2+
3+
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]).
4+
5+
</Note>

‎src/platform-includes/session-replay/install-session-replay/javascript.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
Install the Replay package with NPM or your favourite package manager. Alternatively, you can load the Replay integration via a CDN bundle.
2+
3+
```bash {tabTitle: ESM}
4+
# Make sure to have @sentry/browser or a Framework SDK (e.g. @sentry/react) installed
5+
6+
# Using yarn
7+
yarn add @sentry/replay
8+
9+
# Using npm
10+
npm install --save @sentry/replay
11+
```
12+
13+
```html {tabTitle: CDN}
14+
<!--
15+
Note that the Replay bundle only contains the Replay integration and not the
16+
entire Sentry SDK. You have to add it in addition to the Sentry Browser SDK bundle:
17+
-->
18+
19+
<script
20+
src="https://browser.sentry-cdn.com/{{ packages.version('sentry.javascript.browser') }}/bundle.min.js"
21+
integrity="sha384-{{ packages.checksum('sentry.javascript.browser', 'bundle.min.js', 'sha384-base64') }}"
22+
crossorigin="anonymous"
23+
></script>
24+
25+
<script
26+
src="https://browser.sentry-cdn.com/{{ packages.version('sentry.javascript.browser') }}/replay.min.js"
27+
integrity="sha384-{{ packages.checksum('sentry.javascript.browser', 'replay.min.js', 'sha384-base64') }}"
28+
crossorigin="anonymous"
29+
></script>
30+
```

‎src/platform-includes/session-replay/setup-session-replay/javascript.mdx‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
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.
2+
3+
```javascript {tabTitle: ESM}
4+
// import Sentry from your framework SDK (e.g. @sentry/react) instead of @sentry/browser
5+
import * as Sentry from "@sentry/browser";
6+
7+
import { Replay } from "@sentry/replay";
8+
9+
Sentry.init({
10+
dsn: "___PUBLIC_DSN___",
11+
12+
// This sets the sample rate to be 10%. You may want this to be 100% while
13+
// in development and sample at a lower rate in production
14+
replaysSessionSampleRate: 0.1,
15+
16+
// If the entire session is not sampled, use the below sample rate to sample
17+
// sessions when an error occurs.
18+
replaysOnErrorSampleRate: 1.0,
19+
20+
integrations: [
21+
new Replay({
22+
// Additional SDK configuration goes in here, for example:
23+
maskAllText: true,
24+
blockAllMedia: true
25+
// See below for all available options
26+
})
27+
],
28+
// ...
29+
});
30+
```
31+
32+
```javascript {tabTitle: CDN}
33+
Sentry.init({
34+
dsn: "___PUBLIC_DSN___",
35+
36+
// This sets the sample rate to be 10%. You may want this to be 100% while
37+
// in development and sample at a lower rate in production
38+
replaysSessionSampleRate: 0.1,
39+
40+
// If the entire session is not sampled, use the below sample rate to sample
41+
// sessions when an error occurs.
42+
replaysOnErrorSampleRate: 1.0,
43+
44+
integrations: [
45+
new Sentry.Integrations.Replay({
46+
// Additional SDK configuration goes in here, for example:
47+
maskAllText: true,
48+
blockAllMedia: true
49+
// See below for all available options
50+
})
51+
],
52+
// ...
53+
});
54+
```

‎src/platforms/javascript/common/session-replay/custom-instrumentation/general-configuration.mdx‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: General Configuration
3+
sidebar_order: 410
4+
supported:
5+
- javascript
6+
- javascript.angular
7+
- javascript.ember
8+
- javascript.gatsby
9+
- javascript.nextjs
10+
- javascript.react
11+
- javascript.remix
12+
- javascript.svelte
13+
- javascript.vue
14+
notSupported:
15+
- javascript.capacitor
16+
- javascript.cordova
17+
- javascript.electron
18+
- javascript.wasm
19+
description: "Learn about the general Session Replay configuration fields."
20+
---
21+
22+
<Include name="beta-note-session-replay.mdx" />
23+
24+
## Identifying Users
25+
26+
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/).
27+
28+
```javascript
29+
import * as Sentry from "@sentry/browser";
30+
Sentry.setUser({ email: "[email protected]" });
31+
```
32+
33+
## Start and Stop Recording
34+
35+
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().
36+
37+
```javascript {tabTitle: ESM}
38+
const replay = new Replay(); // This will *NOT* begin recording replays
39+
40+
replay.start(); // Start recording
41+
42+
replay.stop(); // Stop recording
43+
```
44+
45+
```javascript {tabTitle: CDN}
46+
const replay = new Sentry.Integrations.Replay(); // This will *NOT* begin recording replays
47+
48+
replay.start(); // Start recording
49+
50+
replay.stop(); // Stop recording
51+
```
52+
53+
## General Integration Configuration
54+
55+
The following options can be configured on the root level of your browser-based Sentry SDK, in `init({})`:
56+
57+
| key | type | default | description |
58+
| ------------------------ | ------- | ------- | --- |
59+
| 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. |
60+
| 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. |
61+
62+
The following options can be configured as options to the integration, in `new Replay({})`:
63+
64+
| key | type | default | description |
65+
| ------------------- | ------- | ------- | --- |
66+
| 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. |
67+
68+
## Optimization Configuration
69+
70+
The following options can be configured as options to the integration, in `new Replay({})`:
71+
72+
| key | type | default | description |
73+
| ---------------- | ----------------------- | ------- | --- |
74+
| collectFonts | boolean | `false` | Should collect fonts used on the website |
75+
| inlineImages | boolean | `false` | Should inline `<image>` content |
76+
| inlineStylesheet | boolean | `true` | Should inline stylesheets used in the recording |
77+
| recordCanvas | boolean | `false` | Should record `<canvas>` elements |
78+
79+
## rrweb Configuration
80+
81+
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:
82+
83+
```javascript
84+
new Replay({
85+
// any further configuration here is passed directly to rrweb
86+
});
87+
```

‎src/platforms/javascript/common/session-replay/custom-instrumentation/index.mdx‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: Custom Instrumentation
3+
sidebar_order: 4100
4+
supported:
5+
- javascript
6+
- javascript.angular
7+
- javascript.ember
8+
- javascript.gatsby
9+
- javascript.nextjs
10+
- javascript.react
11+
- javascript.remix
12+
- javascript.svelte
13+
- javascript.vue
14+
notSupported:
15+
- javascript.capacitor
16+
- javascript.cordova
17+
- javascript.electron
18+
- javascript.wasm
19+
description: "Learn how to set up General and Privacy aware configuration fields."
20+
---
21+
22+
<Include name="beta-note-session-replay.mdx" />
23+
24+
<PageGrid />

‎src/platforms/javascript/common/session-replay/custom-instrumentation/privacy-configuration.mdx‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: Privacy Configuration
3+
sidebar_order: 4200
4+
supported:
5+
- javascript
6+
- javascript.angular
7+
- javascript.ember
8+
- javascript.gatsby
9+
- javascript.nextjs
10+
- javascript.react
11+
- javascript.remix
12+
- javascript.svelte
13+
- javascript.vue
14+
notSupported:
15+
- javascript.capacitor
16+
- javascript.cordova
17+
- javascript.electron
18+
- javascript.wasm
19+
description: "Configuring Session Replay to maintain user and data privacy."
20+
---
21+
22+
<Include name="beta-note-session-replay.mdx" />
23+
24+
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.
25+
26+
### Masking
27+
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>`.
28+
![Masking example](./session-replay-masking.png)
29+
30+
### Blocking
31+
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>`.
32+
![Blocking example](./session-replay-blocking.png)
33+
34+
### Ignoring
35+
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.
36+
37+
![Ignoring Example](./session-replay-ignore-input.gif)
38+
39+
### Privacy Configuration
40+
41+
The following options can be configured as options to the integration, in `new Replay({})`:
42+
43+
| key | type | default | description |
44+
| ---------------- | ------------------------ | ----------------------------------- | --- |
45+
| maskAllText | boolean | `true` | Mask _all_ text content. Will pass text content through `maskTextFn` before sending to server. |
46+
| blockAllMedia | boolean | `true` | Block _all_ media elements (`img, svg, video, object, picture, embed, map, audio`) |
47+
| 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 `*`. |
48+
| maskAllInputs | boolean | `true` | Mask values of `<input>` elements. Passes input values through `maskInputFn` before sending to server. |
49+
| 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`. |
50+
| 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 `*`. |
51+
| blockClass | string \| RegExp | `'sentry-block'` | Redact all elements that match the class name. See [Blocking](#blocking) above for an example. |
52+
| blockSelector | string | `'[data-sentry-block]'` | Redact all elements that match the DOM selector. See [Blocking](#blocking) above for an example. |
53+
| ignoreClass | string \| RegExp | `'sentry-ignore'` | Ignores all events on the matching input field. See [Ignoring](#ignoring) above for an example. |
54+
| maskTextClass | string \| RegExp | `'sentry-mask'` | Mask all elements that match the class name. See [Masking](#masking) above for an example. |
55+
| maskTextSelector | string | `undefined` | Mask all elements that match the given DOM selector. See [Masking](#masking) above for an example. |

‎src/platforms/javascript/common/session-replay/custom-instrumentation/session-replay-blocking.png‎

38.6 KB
Loading

‎src/platforms/javascript/common/session-replay/custom-instrumentation/session-replay-ignore-input.gif‎

705 KB
Loading

‎src/platforms/javascript/common/session-replay/custom-instrumentation/session-replay-masking.png‎

59.6 KB
Loading

0 commit comments

Comments
 (0)