Skip to content

Commit 8e6fd3e

Browse files
perf2711perf2711
authored
session-replay: add README and update code docs (#258)
* session-replay: add README and update code docs * session-replay: README PR suggestions * session-replay: update README with PII changes --------- Co-authored-by: Sebastian Alex <[email protected]>
1 parent 5d4fe6d commit 8e6fd3e

File tree

2 files changed

+189
-11
lines changed

2 files changed

+189
-11
lines changed

‎packages/session-replay/README.md

+171
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# **Backtrace Session Replay module**
2+
3+
[Backtrace](https://backtrace.io) captures and reports handled and unhandled exceptions in your production software so
4+
you can manage application quality through the complete product lifecycle.
5+
6+
The [`@backtrace/session-replay`](#) module allows your browser application to record user experience before an error occurs. You can view then the recording in Backtrace alongside your error reports.
7+
8+
## Table of Contents
9+
10+
1. [Integration](#integration)
11+
- [Install the package](#install-the-package)
12+
- [Integrate the module](#integrate-the-module)
13+
2. [Features](#features)
14+
- [Event limiting](#event-limiting)
15+
- [Sampling options](#sampling-options)
16+
- [Privacy options](#privacy-options)
17+
3. [Advanced features](#advanced-features)
18+
19+
## Integration
20+
21+
`@backtrace/session-replay` can be integrated with any Backtrace SDK that derives from the `@backtrace/browser` SDK.
22+
23+
### Install the package
24+
25+
```
26+
$ npm install @backtrace/session-replay
27+
```
28+
29+
### Integrate the module
30+
31+
To add the session replay integration, add the following code to the builder:
32+
33+
```ts
34+
import { BacktraceClient, BacktraceConfiguration } from '@backtrace/browser';
35+
import { BacktraceSessionReplayModule } from '@backtrace/session-replay';
36+
37+
// Configure client options
38+
const options: BacktraceConfiguration = {
39+
// Name of the website/application
40+
name: 'MyWebPage',
41+
// Version of the website
42+
version: '1.2.3',
43+
// Submission url
44+
// <universe> is the subdomain of your Backtrace instance (<universe>.backtrace.io)
45+
// <token> can be found in Project Settings/Submission tokens
46+
url: 'https://submit.backtrace.io/<universe>/<token>/json',
47+
};
48+
49+
// Initialize the client with the options
50+
// Make sure to add `useModule` with `BacktraceSessionReplayModule`
51+
const client = BacktraceClient.builder(options)
52+
.useModule(
53+
new BacktraceSessionReplayModule({
54+
maxEventCount: 100,
55+
}),
56+
)
57+
.build();
58+
```
59+
60+
## Features
61+
62+
### Event limiting
63+
64+
You can configure max number of events, that will be sent with the report, using `maxEventCount` option:
65+
66+
```ts
67+
new BacktraceSessionReplayModule({
68+
maxEventCount: 100,
69+
});
70+
```
71+
72+
By default, the event count will be set to 100. To disable max event limit, set `disableMaxEventCount` to `true`. **Note:** disabling the max event count is not recommended and may lead to large reports.
73+
74+
### Sampling options
75+
76+
You can control how events will be captured and sent with the report.
77+
78+
```ts
79+
new BacktraceSessionReplayModule({
80+
sampling: {
81+
input: 'last',
82+
},
83+
});
84+
```
85+
86+
| Option | Values | Default | Description |
87+
| ------------------ | ----------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
88+
| `mousemove` | `boolean`/`number` | `true` | Controls whether mouse movement is recorded, or the interval of mouse movement events in milliseconds (i.e. will not capture more than one event every set time). |
89+
| `mouseInteraction` | `boolean`/`{[MOUSE_INTERACTION]:boolean}` | `true` | Controls all or specific [mouse interactions](#mouse-interactions). |
90+
| `scroll` | `number` | `undefined` | Interval of scrolling events in milliseconds (i.e. will not capture more than one event every set time). |
91+
| `media` | `number` | `undefined` | Interval of media events in milliseconds (i.e. will not capture more than one event every set time). |
92+
| `input` | `'all'`/ `'last'` | `'all'` | Capture either `all` or `last` input events. When set to `last`, only final input will be captured. |
93+
94+
#### Mouse interactions
95+
96+
- `MouseUp`
97+
- `MouseDown`
98+
- `Click`
99+
- `ContextMenu`
100+
- `DblClick`
101+
- `Focus`
102+
- `Blur`
103+
- `TouchStart`
104+
- `TouchMove_Departed`
105+
- `TouchEnd`
106+
- `TouchCancel`
107+
108+
### Privacy options
109+
110+
You can control how information is sent to Backtrace. Use this to mask PII.
111+
112+
For example, if you want to hide all HTML elements that have the `do-not-send` class:
113+
114+
```ts
115+
new BacktraceSessionReplayModule({
116+
privacy: {
117+
blockClass: 'do-not-send',
118+
},
119+
});
120+
```
121+
122+
| Option | Values | Default | Description |
123+
| --------------------- | -------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
124+
| `blockClass` | `string`/`RegExp` | `'bt-block'` | Blocks elements with this class. |
125+
| `blockSelector` | `string` | `undefined` | Blocks elements matching this selector. |
126+
| `ignoreClass` | `string` | `'bt-ignore'` | Ignores elements with this class. |
127+
| `ignoreSelector` | `string` | `undefined` | Ignores elements matching this selector. |
128+
| `ignoreCSSAttributes` | `string[]` | `[]` | Set of CSS attributes that should be ignored. |
129+
| `maskTextClass` | `string`/`RegExp` | `'bt-mask'` | Masks elements with this class. |
130+
| `unmaskTextClass` | `string`/`RegExp` | `'bt-unmask'` | Unmasks elements with this class. |
131+
| `maskTextSelector` | `string` | `undefined` | Masks elements matching this selector. |
132+
| `unmaskTextSelector` | `string` | `undefined` | Unmasks elements matching this selector. |
133+
| `maskAllText` | `boolean` | `true` | If `true`, will mask all text. Use `unmaskTextClass` or `unmaskTextSelector` to unmask. |
134+
| `maskAllInputs` | `boolean` | `true` | If `true`, will mask all inputs. |
135+
| `maskInputOptions` | `{[INPUT_TYPE]:boolean}` | `{ password: true }` | Mask specific [kinds of inputs](#input-types). |
136+
| `maskInputFn` | `(text: string, element: HTMLElement) => string)` | mask with asterisks | Callback to customize input masking. Returned string will be used in masked input. |
137+
| `maskTextFn` | `(text: string, element?: HTMLElement) => string)` | mask with asterisks | Callback to customize text masking. Returned string will be used in masked text. |
138+
| `inspect` | `(event: eventWithTime) => eventWithTime?` | include all events | Callback to inspect the added event. You must return an event for it to be included. Return `undefined` to skip this event. |
139+
140+
#### Input types
141+
142+
- `color`
143+
- `date`
144+
- `datetime-local`
145+
- `email`
146+
- `month`
147+
- `number`
148+
- `range`
149+
- `search`
150+
- `tel`
151+
- `text`
152+
- `time`
153+
- `url`
154+
- `week`
155+
- `textarea`
156+
- `select`
157+
- `password`
158+
159+
## Advanced features
160+
161+
`@backtrace/session-replay` is based on `rrweb`. You can use `advancedOptions` to pass options directly to `rrweb`:
162+
163+
```ts
164+
new BacktraceSessionReplayModule({
165+
advancedOptions: {
166+
checkoutEveryNms: 10000,
167+
},
168+
});
169+
```
170+
171+
See [`rrweb` guide](https://github.com/rrweb-io/rrweb/blob/master/guide.md) for more details.

‎packages/session-replay/src/options.ts

+18-11
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@ import { MaskInputFn, MaskInputOptions, MaskTextFn } from 'rrweb-snapshot';
44

55
export interface BacktraceSessionRecorderSamplingOptions {
66
/**
7-
* Controls whether mouse movement is recorded.
7+
* Controls whether mouse movement is recorded,
8+
* or the interval of mouse movement events in milliseconds
9+
* (i.e. will not capture more than one event every set time).
810
* @default true
911
*/
1012
readonly mousemove?: boolean | number;
@@ -50,13 +52,15 @@ export interface BacktraceSessionRecorderSamplingOptions {
5052
| Partial<Record<string, boolean>>;
5153

5254
/**
53-
* Interval of scrolling events in milliseconds (i.e. will not capture more than one event every set time).
55+
* Interval of scrolling events in milliseconds
56+
* (i.e. will not capture more than one event every set time).
5457
* @default undefined
5558
*/
5659
readonly scroll?: number;
5760

5861
/**
59-
* Interval of media events in milliseconds (i.e. will not capture more than one event every set time).
62+
* Interval of media events in milliseconds
63+
* (i.e. will not capture more than one event every set time).
6064
* @default undefined
6165
*/
6266
readonly media?: number;
@@ -78,7 +82,7 @@ export interface BacktraceSessionReplayPrivacyOptions {
7882
readonly blockClass?: string | RegExp;
7983

8084
/**
81-
* Use a `string` to configure which selector should be blocked.
85+
* Blocks elements matching this selector.
8286
* @default undefined
8387
*/
8488
readonly blockSelector?: string;
@@ -90,21 +94,21 @@ export interface BacktraceSessionReplayPrivacyOptions {
9094
readonly ignoreClass?: string;
9195

9296
/**
93-
* Use a `string` to configure which selector should be ignored.
97+
* Ignores elements matching this selector.
9498
* @default undefined
9599
*/
96100
readonly ignoreSelector?: string;
97101

98102
/**
99-
* Array of CSS attributes that should be ignored.
103+
* Set of CSS attributes that should be ignored.
100104
*/
101-
readonly ignoreCSSAttributes?: Set<string>;
105+
readonly ignoreCSSAttributes?: Set<string> | string[];
102106

103107
/**
104108
* Masks elements with this class.
105109
* @default "bt-mask"
106110
*/
107-
readonly maskTextClass?: string;
111+
readonly maskTextClass?: string | RegExp;
108112

109113
/**
110114
* Unmasks elements with this class.
@@ -167,7 +171,8 @@ export interface BacktraceSessionReplayPrivacyOptions {
167171
* @returns masked text
168172
* @default undefined
169173
* @example
170-
* // replace text with letter A repeated for the text length if element has class "mask-a"
174+
* // replace text with letter A repeated for the text length
175+
* // if element has class "mask-a"
171176
* maskInputFn = (text, element) =>
172177
* element.classList.contains('mask-a')
173178
* ? 'A'.repeat(text.length)
@@ -187,7 +192,8 @@ export interface BacktraceSessionReplayPrivacyOptions {
187192
readonly maskTextFn?: MaskTextFn;
188193

189194
/**
190-
* Callback to inspect the added event. You must return an event for it to be included.
195+
* Callback to inspect the added event.
196+
* You must return an event for it to be included.
191197
*
192198
* Return `undefined` to skip this event.
193199
* @param event Event to be added to the report.
@@ -223,7 +229,8 @@ export interface BacktraceSessionRecorderOptions {
223229
readonly privacy?: BacktraceSessionReplayPrivacyOptions;
224230

225231
/**
226-
* Options passed to `rrweb.record` function. Refer to `rrweb` documentation for more information.
232+
* Options passed to `rrweb.record` function.
233+
* Refer to `rrweb` documentation for more information.
227234
*/
228235
readonly advancedOptions?: recordOptions<Event>;
229236
}

0 commit comments

Comments
 (0)