docs(replay): Replay Issue types & hydration errors

docs/platforms/javascript/common/session-replay/issue-types.mdx

@@ -0,0 +1,46 @@
+---
+title: Replay Issues
+sidebar_order: 4300
+notSupported:
+  - javascript.cordova
+  - javascript.wasm
+  - javascript.bun
+  - javascript.deno
+  - javascript.node
+  - javascript.aws-lambda
+  - javascript.azure-functions
+  - javascript.connect
+  - javascript.express
+  - javascript.fastify
+  - javascript.gcp-functions
+  - javascript.hapi
+  - javascript.koa
+  - javascript.nestjs
+description: "Learn about the Issue types that Session Replay can detect."
+---
+
+A _[replay issue](/product/issues/issue-details/replay-issues/)_ is an issue detected using captured Session Replay data. If your application is configured with [Session Replay](/product/session-replay/), problems will be detected on the server side during replay ingest, and grouped into issues. We group similar events into issues based on a fingerprint. For replay issues, a fingerprint is primarily based on the problem type and the url or transaction name where the problem occurred.
+
+You can configure which issue types are created by visiting Project Settings > Replay and toggling detection on or off for each issue type.
+
+![Replay settings page](./img/replay-settings.png)
+
+## Configuring Rage Click Issues
+
+"Dead clicks" (also called "slow clicks") are only detected on `<button>`, `<input>`, and `<a>` elements that don't lead to updates to the DOM or a page scroll within 7 seconds. When the user clicks on one of these elements 3 or more times within that 7-second timeframe, it indicates frustration, and the SDK registers a ["rage click"](/product/issues/issue-details/replay-issues/rage-clicks/).
+
+Sometimes rage or dead clicks will be detected on elements which are not expected to mutate the DOM, like a "Print" or "Download" button. In this case, you can configure `slowClickIgnoreSelectors`, which will prevent those buttons from generating new issues.
+
+## Configuring Hydration Errors
+
+When a [hydration error](/product/issues/issue-details/replay-issues/hydration-error/) occurs in your React app, the SDK will emit an error object as well as a replay breadcrumb, both of which contain data about the hydration problem. Both of these are sent to the server for processing. When you're looking at the issue stream you'll see Hydration Error issues which could come from either data source. However you will only see the diff tools which make debugging easier if a replay is associated with the error.
+
+For this reason we recommend having both [Inbound Filter](/concepts/data-management/filtering/) enabled and the "Create Hydration Error Issues" Replay setting enabled as well. This is also the default!
+
+You can have your preferences configured in one of four ways:
+| Inbound Filters | Replay Hydration Error toggle | Result |
+| --- | --- | --- |
+| enabled | enabled | (recommended) Issue created based on replay breadcrumb data. |
+| enabled | disabled | No issues will be created. |
+| disabled | enabled | Two issues created from both replay breadcrumb, and error data. The issues are duplicates. |
+| disabled | disabled | Issue created from captured error data. |

docs/platforms/javascript/common/session-replay/troubleshooting.mdx

@@ -46,6 +46,27 @@ Due to [browser limitations](https://developer.mozilla.org/en-US/docs/Web/SVG/El
 </Alert>
 </Expandable>
 
+<Expandable title="Why am I seeing too many or too few rage clicks?" permalink>
+
+There might be fewer rage clicks than you expect if the user stopped waiting for the site to respond before the 7 second threshold. This is why the rage click issues that you *do* see are so valuable, because the user that clicked at least 3 times and continued waiting at least 7 seconds for the site to respond is likely very frustrated.
+
+You might also see more rage clicks than you expected from buttons that don't trigger a DOM mutation or page scroll (such as "Print" and "Download" buttons). There is no reliable way for the SDK to detect that a download or print has initiated, so a slow click might be generated even if the button is not actually "dead". For these cases, you can configure the SDK via `slowClickIgnoreSelectors` - see [Configuration](/platforms/javascript/session-replay/configuration/) for more details.
+
+For example, to ignore detection of dead and rage clicks for download links in your application:
+
+```javascript
+Sentry.replayIntegration({
+  slowClickIgnoreSelectors: [
+    ".download",
+    // Any link with a label including "download" (case-insensitive)
+    'a[label*="download" i]',
+  ],
+});
+```
+
+</Expandable>
+
+
 <Expandable title="Why can't I see the full HTTP request body or all the headers?" permalink>
 
 By default, Replay will capture basic information about all outgoing fetch and XHR requests in your application. This includes the URL, request and response body size, method, and status code.

docs/platforms/javascript/common/session-replay/understanding-sessions.mdx

@@ -1,6 +1,6 @@
 ---
 title: Understanding Sessions
-sidebar_order: 4300
+sidebar_order: 4400
 notSupported:
   - javascript.cordova
   - javascript.wasm

docs/product/issues/issue-details/replay-issues/hydration-error.mdx

@@ -0,0 +1,48 @@
+---
+title: Hydration Error
+sidebar_order: 50
+description: "Learn about hydration errors."
+---
+
+Hydration errors are a React-specific problem that happen when the initial client UI does not match what was rendered on the server. They can result in extra work for the browser, and a slower pageload experience for users.
+
+## Prerequisites for Seeing Hydration Error Diff Tools
+
+Hydration Errors can come into your issue stream either as regular error events, or they could be detected inside a replay session and converted into an issue by the server. Read more about
+[configuring hydration errors](/platforms/javascript/session-replay/issue-types/) to learn about the differences.
+
+If the hydration error event instance has an associated replay session, then you will see diff tools on the issue details page to make debugging the hydration error easier.
+
+## Debugging Hydration Errors
+
+Hydration errors represent a mismatch between the server-rendered HTML, and the client-rendered HTML. So it's beneficial to compare the before and after state of a webpage to understand what's changed, and decide how to make those two states consistent. To do this, we provide a few diff tools to see the differences -- both visually and by looking at the rendered HTML itself.
+
+Generally the visual tools are a good place to start to identify the issue, but keep in mind that sometimes differences can appear below the fold, or there can be differences in hidden DOM nodes or attributes, so inspecting the HTML is important too.
+
+### Example Error
+
+In the example below we'll look at a hydration error and see how each tool helps to debug the problem.
+
+The problem is that code highlighting is not applied on the server. When the server renders the PHP code block in the bottom-center of the page, all the code has a white font color. After hydration syntax highlighting is applied, the code snippet is colorful.
+
+#### Image Slider Tool
+
+The image slider tool allows for comparing the two page states by overlaying the images on top of each other. Click and drag the purple line to reveal one image or the other.
+
+![image slider tool](./img/hydration-error-image-slider-tool.png)
+
+#### Side by Side Image Tool
+
+View images side by side to see large chunks of the page that may differ.
+
+![side by side image tool](./img/hydration-error-side-by-side-image-tool.png)
+
+#### HTML Diff Tool
+
+The HTML diff tool is a basic HTML comparison. It is useful if the hydration error is caused by hidden DOM nodes, different attributes on a DOM node, or mismatched content below the fold.
+
+![html diff tool](./img/hydration-error-html-diff-tool.png)
+
+## Privacy
+
+The diff tools all rely on replay data, so any PII data within the webpage will be masked or blocked before being sent to the server. Read more about [Protecting user privacy in Session Replay](/security-legal-pii/scrubbing/protecting-user-privacy/) and [how to configure Session Replay to maintain user privacy](/platforms/javascript/session-replay/privacy/).

docs/product/issues/issue-details/replay-issues/index.mdx

@@ -1,58 +1,21 @@
 ---
-title: Rage Click Issues
+title: Replay Issues
 sidebar_order: 30
-description: "Learn about Session Replay rage click issues."
+description: "Learn more about which replay issues Sentry detects."
 ---
 
-If you've enabled [Session Replay](/product/explore/session-replay/), you'll be able to see rage click issues on the [**Issues**](https://sentry.io/orgredirect/organizations/:orgslug/issues/) page in Sentry. Rage clicks are a series of consecutive clicks on the same unresponsive element. They are a sure sign of user frustration and most likely deserve your attention.
+If you've enabled [Session Replay](/product/explore/session-replay/), you'll be able to see new issue types on the [**Issues**](https://sentry.io/orgredirect/organizations/:orgslug/issues/) page in Sentry.
 
-![Rage click issue](./img/Rage-click-issue-in-issue-stream.png)
-
-## Prerequisites for Seeing Rage Clicks
-
-In order to see rage clicks in your issue stream on the **Issues** page, your organization needs to:
-
-- Be sending [session replay events](/product/explore/session-replay/getting-started/)
-- Enable the JavaScript SDK (or framework-specific bundle), version 7.60.1 or higher
+## Quota Consumption
 
 <Note>
-While you can enable **session replay** with JavaScript SDK version 7.27.0, or higher, you'll need to have version 7.60.1 or higher in order to be able to see **rage click issues**.
+Replay issues do not consume issue quota.
 </Note>
 
-## Detection Criteria
-
-"Slow clicks" (also called "dead clicks") are only detected on `<button>`, `<input>`, and `<a>` elements that don't lead to updates to the DOM or a page scroll within 7 seconds). When the user clicks on one of these elements 3 or more times within that 7 second time frame, it indicates frustration, and the SDK registers a "rage click". 
-
-### Why am I seeing too many or too few rage clicks?
-There might be fewer rage clicks than you expect if the user stopped waiting for the site to respond before the 7 second threshold and instead chose to to something else. This is why the rage click issues that you *do* see are so valuable, because the user that clicked at least 3 times and continued waiting at least 7 seconds for the site to respond is likely very frustrated.
-
-You might also see more rage clicks than you expected from buttons that don't trigger a DOM mutation or page scroll (such as Print and Download buttons). There is no reliable way for the SDK to detect that a download or print has initiated, so a slow click might be generated even if the button is not actually "dead". For these cases, you can configure the SDK via `slowClickIgnoreSelectors` - see [Configuration](/platforms/javascript/session-replay/configuration/) for more details.
-
-For example, to ignore detection of dead and rage clicks for download links in your application:
-
-```javascript
-Sentry.replayIntegration({
-  slowClickIgnoreSelectors: [
-    ".download",
-    // Any link with a label including "download" (case-insensitive)
-    'a[label*="download" i]',
-  ],
-});
-```
-
-## Get Rage Click Alerts
-
-To set up alerts and get notified when a rage click occurs, follow these steps:
-
-1. Create a new [Alert Rule](https://sentry.sentry.io/alerts/new/issue/) in Sentry.
-2. In the "Set conditions" section, set the "IF" filter to "The issue's category is equal to", then choose "Replay" from the dropdown.
-3. Add an optional filter if you like.
-5. Choose the action to be performed in the "THEN" dropdown.
-6. Decide how often you'd like Sentry to look for rage click issues.
-7. Lastly, name your alert and add an owner.
+When a replay is created it consumes [replay quota](/pricing/quotas/manage-replay-quota/) (not to be confused with [error quota](/pricing/quotas/manage-event-stream-guide/)). As the replay session is being processed by the server Sentry detects the replay issue types listed below and groups those into issues. These errors are created on the backend after ingest and do not comsume error quota. They will not appear on your [stats](https://sentry.io/orgredirect/organizations/:orgslug/stats/) page under the "Total Errors" or "Accepted Errors" graphs. You are not billed for their volume.
 
-## Turn Off Rage Click Issues
+## Replay Issue Types
 
-If you don't want to see rage click issues, you can disable them by going to the **Settings** page in Sentry, clicking "Projects", and selecting the project for which you want to disable rage clicks. From here, select "Replays" under the "PROCESSING" heading and toggle off "Create Rage Click Issues".
+- [Rage clicks](/product/issues/issue-details/replay-issues/rage-clicks/) are a series of consecutive clicks on the same unresponsive page element. They are a strong signal of user frustration and most likely deserve your attention.
 
-![Turning off rage click issues](./img/Turning-off-rage-clicks-toggle.png)
+- [Hydration errors](/product/issues/issue-details/replay-issues/hydration-error/) are a React-specific problem that happen when the initial UI does not match what was rendered on the server. They can result in extra work for the browser, and a slower pageload experience for users.

docs/product/issues/issue-details/replay-issues/rage-clicks.mdx

@@ -0,0 +1,47 @@
+---
+title: Rage Click Issues
+sidebar_order: 40
+description: "Learn about Session Replay rage click issues."
+---
+
+If you've enabled [Session Replay](/product/explore/session-replay/), you'll be able to see rage click issues on the [**Issues**](https://sentry.io/orgredirect/organizations/:orgslug/issues/) page in Sentry. Rage clicks are a series of consecutive clicks on the same unresponsive page element. They are a strong signal of user frustration and most likely deserve your attention.
+
+![Rage click issue](./img/rage-click-issue-details.png)
+
+## Prerequisites for Seeing Rage Clicks
+
+In order to see rage clicks in your issue stream on the **Issues** page, your organization needs to:
+
+- Be sending [Session Replay events](/product/explore/session-replay/getting-started/)
+- Enable the JavaScript SDK (or framework-specific bundle), version 7.60.1 or higher
+
+<Note>
+While you can enable **Session Replay** with JavaScript SDK version 7.27.0, or higher, you'll need to have version 7.60.1 or higher in order to be able to see **rage click issues**.
+</Note>
+
+## Detection Criteria
+
+"Dead clicks" (also called "slow clicks") are only detected on `<button>`, `<input>`, and `<a>` elements that don't lead to updates to the DOM or a page scroll within 7 seconds. When the user clicks on one of these elements 3 or more times within that 7-second timeframe, it indicates frustration, and the SDK registers a "rage click".
+
+You can configure Replay to ignore specific selectors if you are seeing [too many rage clicks](/platforms/javascript/session-replay/troubleshooting/#why-am-i-seeing-too-many-or-too-few-rage-clicks) reported. For example, you might want to ignore clicks on "Print" or "Download" buttons.
+
+## Get Rage Click Alerts
+
+To set up alerts and get notified when a rage click occurs, follow these steps:
+
+1. Create a new [Alert Rule](https://sentry.io/orgredirect/organizations/:orgslug/alerts/new/issue/) in Sentry.
+2. In the "Set conditions" section, set the "IF" filter to "The issue's category is equal to", then choose "Replay" from the dropdown.
+3. Add an optional filter if you like.
+5. Choose the action to be performed in the "THEN" dropdown.
+6. Decide how often you'd like Sentry to look for rage click issues.
+7. Lastly, name your alert and add an owner.
+
+## Turn Off Rage Click Issues
+
+If you don't want to see rage click issues, you can disable them, follow these steps:
+1. Go to the [Settings > Projects](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/) page in Sentry.
+2. Select a project from the list.
+3. Go to the "Replays" sub-page for this project under the "Processing" heading.
+4. Toggle off "Create Rage Click Issues".
+
+![Turning off rage click issues](./img/Turning-off-rage-clicks-toggle.png)