You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: packages/replay/README.md
+58-28Lines changed: 58 additions & 28 deletions
Original file line number
Diff line number
Diff line change
@@ -1,11 +1,12 @@
1
-
# sentry-replay
1
+
# Sentry Session Replay
2
2
3
3
Note: Session Replay is currently in beta.
4
4
5
5
## Pre-requisites
6
6
7
-
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.x`.
7
+
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.23.0`.
8
8
9
+
Make sure to use the exact same version of `@sentry/replay` as your other Sentry package(s), e.g. `@sentry/browser` or `@sentry/react`.
9
10
10
11
`@sentry/replay` requires Node 12+, and browsers newer than IE11.
11
12
@@ -34,27 +35,21 @@ import { Replay } from '@sentry/replay';
34
35
35
36
Sentry.init({
36
37
dsn:'__DSN__',
38
+
39
+
// This sets the sample rate to be 10%. You may want this to be 100% while
40
+
// in development and sample at a lower rate in production
41
+
replaysSampleRate:0.1,
42
+
43
+
// If the entire session is not sampled, use the below sample rate to sample
44
+
// sessions when an error occurs.
45
+
replaysOnErrorSampleRate:1.0,
46
+
37
47
integrations: [
38
48
newReplay({
39
-
// This sets the sample rate to be 10%. You may want this to be 100% while
40
-
// in development and sample at a lower rate in production
41
-
sessionSampleRate:0.1,
42
-
43
-
// If the entire session is not sampled, use the below sample rate to sample
44
-
// sessions when an error occurs.
45
-
errorSampleRate:1.0,
46
-
47
-
// Mask all text content with asterisks (*). Passes text
48
-
// content through to `maskTextFn` before sending to server.
49
-
//
50
-
// Defaults to true, uncomment to change
51
-
// maskAllText: true,
52
-
53
-
// Block all media elements (img, svg, video, object,
54
-
// picture, embed, map, audio)
55
-
//
56
-
// Defaults to true, uncomment to change
57
-
// blockAllMedia: true,
49
+
// Additional SDK configuration goes in here, for example:
50
+
maskAllText:true,
51
+
blockAllMedia:true
52
+
// See below for all available options
58
53
})
59
54
],
60
55
// ...
@@ -96,24 +91,37 @@ Alternatively, rather than recording an entire session, you can capture a replay
96
91
97
92
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:
98
93
99
-
-`sessionSampleRate` - The sample rate for replays that begin recording immediately and last the entirety of the user's session.
100
-
-`errorSampleRate` - 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.
94
+
-`replaysSampleRate` - The sample rate for replays that begin recording immediately and last the entirety of the user's session.
95
+
-`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.
101
96
102
-
Sampling occurs when the session is first started. `sessionSampleRate` is evaluated first. If it is sampled, then the replay recording begins. Otherwise, `errorSampleRate` 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.
97
+
Sampling occurs when the session is first started. `replaysSampleRate` is evaluated first. If it is sampled, then the replay recording begins. Otherwise, `replaysOnErrorSampleRate` 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.
103
98
104
99
105
100
## Configuration
106
101
107
-
### General Configuration
102
+
### SDK Configuration
103
+
104
+
The following options can be configured on the root level of your browser-based Sentry SDK, in `init({})`:
| replaysSampleRate | 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. |
110
+
| 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.
111
+
112
+
### General Integration Configuration
113
+
114
+
The following options can be configured as options to the integration, in `new Replay({})`:
| 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) |
112
-
| 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). |
113
118
| 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. |
114
119
120
+
115
121
### Privacy Configuration
116
122
123
+
The following options can be configured as options to the integration, in `new Replay({})`:
| maskAllText | boolean |`true`| Mask _all_ text content. Will pass text content through `maskTextFn` before sending to server. |
@@ -126,16 +134,30 @@ Sampling occurs when the session is first started. `sessionSampleRate` is evalua
126
134
| blockSelector | string |`'[data-sentry-block]'`| Redact all elements that match the DOM selector. See [privacy](#blocking) section for an example. |
127
135
| ignoreClass | string \| RegExp |`'sentry-ignore'`| Ignores all events on the matching input field. See [privacy](#ignoring) section for an example. |
128
136
| maskTextClass | string \| RegExp |`'sentry-mask'`| Mask all elements that match the class name. See [privacy](#masking) section for an example. |
137
+
| maskTextSelector | string |`undefined`| Mask all elements that match the given DOM selector. See [privacy](#masking) section for an example. |
129
138
130
139
### Optimization Configuration
131
140
141
+
The following options can be configured as options to the integration, in `new Replay({})`:
| collectFonts | boolean |`false`| Should collect fonts used on the website |
135
146
| inlineImages | boolean |`false`| Should inline `<image>` content |
136
147
| inlineStylesheet | boolean |`true`| Should inline stylesheets used in the recording |
137
148
| recordCanvas | boolean |`false`| Should record `<canvas>` elements |
138
-
| slimDOMOptions | Record<string, boolean> |`{}`| Remove unnecessary parts of the DOM <br /> Available keys: `script, comment, headFavicon, headWhitespace, headMetaDescKeywords, headMetaSocial, headMetaRobots, headMetaHttpEquiv, headMetaAuthorship, headMetaVerification`|
149
+
150
+
151
+
### rrweb Configuration
152
+
153
+
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:
154
+
155
+
```js
156
+
newReplay({
157
+
// any further configuration here is passed directly to rrweb
158
+
});
159
+
```
160
+
139
161
140
162
## Privacy
141
163
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.
@@ -153,3 +175,11 @@ Ignoring only applies to form inputs. Events will be ignored on the input elemen
0 commit comments