docs(replay): Update replay README

packages/replay/README.md

@@ -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.
 
@@ -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
  })
  ],
  // ...
@@ -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. |
@@ -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.
@@ -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.