feat(replay): Add slow click detection docs (#8658)

--------- Co-authored-by: Michelle Zhang <[email protected]> Co-authored-by: Liza Mock <[email protected]> Co-authored-by: Bruno Garcia <[email protected]> Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
getsentry · Dec 15, 2023 · baff6b1 · baff6b1 · vercel · Dec 15, 2023
1 parent 40df9e1
commit baff6b1
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 13 deletions.
diff --git a/src/platforms/javascript/common/session-replay/configuration.mdx b/src/platforms/javascript/common/session-replay/configuration.mdx
@@ -20,19 +20,20 @@ The following options can be configured on the root level of your browser-based
 
 The following can be configured as integration options in `new Replay({})`:
 
-| Key                     | Type                                | Default     | Description                                                                                                                                                                  |
-| ----------------------- | ----------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| stickySession           | `boolean`                           | `true`      | Keep track of users across page loads. Note, because closing a tab ends the session, a single user using multiple tabs will be recorded as multiple sessions.                |
-| mutationLimit           | `number `                           | 10000       | The upper bound of mutations to process before Session Replay stops recording due to performance impacts. See [Mutation Limits](#mutation-limits)                            |
-| mutationBreadcrumbLimit | `number `                           | 750         | The upper bound of mutations to process before Session Replay sends a breadcrumb to warn of large mutations. See [Mutation Limits](#mutation-limits)                         |
-| minReplayDuration       | `number`                            | 5000        | The length of the replay, **in milliseconds**, before the SDK should start sending to Sentry. Max value is 15000.                                                            |
-| workerUrl               | `string`                            | `undefined` | A URL for a self-hosted worker for compression Replay data. See [Using a Custom Compression Worker](#using-a-custom-compression-worker) to learn more.                       |
-| networkDetailAllowUrls  | <code>(string\|RegExp)[]</code>     | `[]`        | Capture request and response details for XHR and fetch requests that match the given URLs.                                                                                   |
-| networkCaptureBodies    | `boolean`                           | `true`      | Decide whether to capture request and response bodies for URLs defined in `networkDetailAllowUrls`.                                                                          |
-| networkRequestHeaders   | `string[]`                          | `[]`        | Additional request headers to capture for URLs defined in `networkDetailAllowUrls`. See [Network Details](#network-details) to learn more.                                   |
-| networkResponseHeaders  | `string[]`                          | `[]`        | Additional response headers to capture for URLs defined in `networkDetailAllowUrls`. See [Network Details](#network-details) to learn more.                                  |
-| beforeAddRecordingEvent | <code>(event) => event\|null</code> | `i => i`    | Filter additional recording events that include console logs and network requests/responses.                                                                                 |
-| beforeErrorSampling     | `(event) => boolean`                | `i => true` | Filter error events which should be skipped for error sampling. Return `false` if error sampling should be skipped for this error event, or `true` to sample for this error. |
+| Key                      | Type                                | Default     | Description                                                                                                                                                                  |
+| ------------------------ | ----------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| stickySession            | `boolean`                           | `true`      | Keep track of users across page loads. Note, because closing a tab ends the session, a single user using multiple tabs will be recorded as multiple sessions.                |
+| mutationLimit            | `number `                           | 10000       | The upper bound of mutations to process before Session Replay stops recording due to performance impacts. See [Mutation Limits](#mutation-limits)                            |
+| mutationBreadcrumbLimit  | `number `                           | 750         | The upper bound of mutations to process before Session Replay sends a breadcrumb to warn of large mutations. See [Mutation Limits](#mutation-limits)                         |
+| minReplayDuration        | `number`                            | 5000        | The length of the replay, **in milliseconds**, before the SDK should start sending to Sentry. Max value is 15000.                                                            |
+| workerUrl                | `string`                            | `undefined` | A URL for a self-hosted worker for compression Replay data. See [Using a Custom Compression Worker](#using-a-custom-compression-worker) to learn more.                       |
+| networkDetailAllowUrls   | <code>(string\|RegExp)[]</code>     | `[]`        | Capture request and response details for XHR and fetch requests that match the given URLs.                                                                                   |
+| networkCaptureBodies     | `boolean`                           | `true`      | Decide whether to capture request and response bodies for URLs defined in `networkDetailAllowUrls`.                                                                          |
+| networkRequestHeaders    | `string[]`                          | `[]`        | Additional request headers to capture for URLs defined in `networkDetailAllowUrls`. See [Network Details](#network-details) to learn more.                                   |
+| networkResponseHeaders   | `string[]`                          | `[]`        | Additional response headers to capture for URLs defined in `networkDetailAllowUrls`. See [Network Details](#network-details) to learn more.                                  |
+| beforeAddRecordingEvent  | <code>(event) => event\|null</code> | `i => i`    | Filter additional recording events that include console logs and network requests/responses.                                                                                 |
+| beforeErrorSampling      | `(event) => boolean`                | `i => true` | Filter error events which should be skipped for error sampling. Return `false` if error sampling should be skipped for this error event, or `true` to sample for this error. |
+| slowClickIgnoreSelectors | `string[]`                          | `[]`        | Ignore slow/rage click detection on elements matching the given CSS selector(s).                                                                                             |
 
 ## Privacy Configuration
 

diff --git a/src/platforms/javascript/common/session-replay/troubleshooting.mdx b/src/platforms/javascript/common/session-replay/troubleshooting.mdx
@@ -62,6 +62,32 @@ Because of the complexity of the browser environment, there's a significant amou
 
 We're always working on ways to reduce the bundle size. Additionally, there are steps you can take in order to reduce the size of Session Replay based on your specific use case. See [Tree Shaking](../../configuration/tree-shaking/) for more information.
 
+## How does Rage Click detection work?
+
+The Replay SDK tries to detect cases where a user clicked on something, but nothing happened. This is called a "Dead Click" -- a click that seems to be "dead" and does nothing, from the user's perspective. This can happen if a bug prevents the UI from being correctly updated after a button is clicked.
+
+The way that the Replay SDK detects this is by checking if a click on a `<button>` or `<a>` element doesn't lead to either updates to the DOM or a page scroll. If within 7 seconds no updates are detected, the SDK will generate a "Slow Click" in the Replay UI. (We call it a "Slow Click" because it may be possible that something will happen after the 7s, but we chose this as a cutoff time.)
+
+Another concept related to this is "Rage Clicks". A "Rage Click" is when a user clicks on an element many times, which indicates frustration that something isn't working.
+
+When a Slow Click and a Rage Click come together, we have a very good indicator that something is actually wrong, and the Replay SDK will generate a "Rage Click" for this.
+
+Note that there are some limitations to this. On the one hand, there may be _false negatives_ -- we cannot detect all cases; for example, imagine a user clicks a "dead" button, but then clicks a different button afterwards that leads to a DOM update. In this case, since we cannot attribute the DOM update to a specific button, we'll _not_ capture this slow click.
+
+On the other hand, there may be _false positives_. For example, if a user clicks a link that leads to a file download, there is no reliable way to detect that a download was initiated, so a Slow Click may be generated even if the button is not actually "dead". For these cases, you can configure the SDK via `slowClickIgnoreSelectors` - see <PlatformLink to='/session-replay/configuration'>Configuration</PlatformLink> for more details.
+
+For example, you could ignore detection of dad and rage clicks for download links in your application like this:
+
+```javascript
+new Sentry.Replay({
+  slowClickIgnoreSelectors: [
+    ".download",
+    // Any link with a label including "download" (case-insensitive)
+    'a[label*="download" i]',
+  ],
+});
+```
+
 ## I See the Message: "A large number of mutations was detected (N). This can slow down the Replay SDK and impact your customers."
 
 The Sentry SDK attempts to minimize potential [performance overhead](/product/session-replay/performance-overhead/#how-is-session-replay-optimized) in a few different ways. For example, by keeping track of the number of DOM mutations that are happening then disabling recording when a large number of changes are detected. Many simultaneous mutations can slow down a web page whether Session Replay is installed or not, but when a large number of mutations happen, the Replay client can incur an additional slowdown because it records each change.