Skip to content

docs(replay): Update replay README #6398

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Dec 5, 2022
Merged

docs(replay): Update replay README #6398

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
9130eae
docs(replay): Update replay README
mydea Dec 2, 2022
7fcdef3
docs(replay): Add section about error linking
mydea Dec 2, 2022
9f564fe
docs: Remove mention of old sample options
mydea Dec 2, 2022
4327317
doc: Fix package name in readme
mydea Dec 2, 2022
e50b592
docs: Update readme
mydea Dec 2, 2022
0e56979
docs: Update readme
mydea Dec 2, 2022
0634950
docs: Fix typo
mydea Dec 2, 2022
79a4a78
doc: minor typo
mydea Dec 2, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 58 additions & 28 deletions packages/replay/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
# sentry-replay
# Sentry Session Replay

Note: Session Replay is currently in beta.

## 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.x`.
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`.

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.

Expand Down Expand Up @@ -34,27 +35,21 @@ import { Replay } from '@sentry/replay';

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
replaysSampleRate: 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({
// 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
sessionSampleRate: 0.1,

// If the entire session is not sampled, use the below sample rate to sample
// sessions when an error occurs.
errorSampleRate: 1.0,

// Mask all text content with asterisks (*). Passes text
// content through to `maskTextFn` before sending to server.
//
// Defaults to true, uncomment to change
// maskAllText: true,

// Block all media elements (img, svg, video, object,
// picture, embed, map, audio)
//
// Defaults to true, uncomment to change
// blockAllMedia: true,
// Additional SDK configuration goes in here, for example:
maskAllText: true,
blockAllMedia: true
// See below for all available options
})
],
// ...
Expand Down Expand Up @@ -96,24 +91,37 @@ Alternatively, rather than recording an entire session, you can capture a replay

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:

- `sessionSampleRate` - The sample rate for replays that begin recording immediately and last the entirety of the user's session.
- `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.
- `replaysSampleRate` - 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.

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.
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.


## Configuration

### General Configuration
### SDK Configuration

The following options can be configured on the root level of your browser-based Sentry SDK, in `init({})`:


| key | type | default | description |
| ------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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. |
| 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.

### General Integration Configuration

The following options can be configured as options to the integration, in `new Replay({})`:

| key | type | default | description |
| ------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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) |
| 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). |
| 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. |


### 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. |
Expand All @@ -126,16 +134,30 @@ Sampling occurs when the session is first started. `sessionSampleRate` is evalua
| blockSelector | string | `'[data-sentry-block]'` | Redact all elements that match the DOM selector. See [privacy](#blocking) section for an example. |
| ignoreClass | string \| RegExp | `'sentry-ignore'` | Ignores all events on the matching input field. See [privacy](#ignoring) section for an example. |
| maskTextClass | string \| RegExp | `'sentry-mask'` | Mask all elements that match the class name. See [privacy](#masking) section for an example. |
| maskTextSelector | string | `undefined` | Mask all elements that match the given DOM selector. See [privacy](#masking) section for an example. |

### 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 |
| slimDOMOptions | Record<string, boolean> | `{}` | Remove unnecessary parts of the DOM <br /> Available keys: `script, comment, headFavicon, headWhitespace, headMetaDescKeywords, headMetaSocial, headMetaRobots, headMetaHttpEquiv, headMetaAuthorship, headMetaVerification` |


### 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:

```js
new Replay({
// any further configuration here is passed directly to rrweb
});
```


## Privacy
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.
Expand All @@ -153,3 +175,11 @@ Ignoring only applies to form inputs. Events will be ignored on the input elemen

https://user-images.githubusercontent.com/79684/192815134-a6451c3f-d3cb-455f-a699-7c3fe04d0a2e.mov

## 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.