feat(replay): Add examples for custom sampling (#8035)

* feat(replay): Add examples for custom sampling

Give more specific example scenarios for custom sampling.

Closes #7839

* style(lint): Auto commit lint changes

* Apply suggestions from code review

Co-authored-by: Liza Mock <liza.mock@sentry.io>

* update examples

* Update src/platforms/javascript/common/session-replay/understanding-sessions.mdx

Co-authored-by: Liza Mock <liza.mock@sentry.io>

* Update index.mdx (#7994)

* Update index.mdx (#8032)

Co-authored-by: Shana Matthews <shana.l.matthews@gmail.com>

* updates

* Apply suggestions from code review

Co-authored-by: Francesco Novy <francesco.novy@sentry.io>

* continue to record replay instead of stop

---------

Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
Co-authored-by: Liza Mock <liza.mock@sentry.io>
Co-authored-by: JGS3089 <145158937+JGS3089@users.noreply.github.com>
Co-authored-by: Shana Matthews <shana.l.matthews@gmail.com>
Co-authored-by: Francesco Novy <francesco.novy@sentry.io>

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

@@ -96,3 +96,78 @@ await replay.flush();
 In `session` mode, this will upload any pending recording data to Sentry. In `buffer` mode, this will upload any pending recording data to Sentry and then continue recording, the same as when an error is sampled with `replaysOnErrorSampleRate`.
 
 Note that it's safe to call `flush()` at any time, even if Session Replay is stopped, in which case, it will do nothing.
+
+## Examples of Custom Sampling
+
+There are ways to enable custom sampling if you're interested in tracking a particular action or group, for example, a specific segment of users or a problematic URL.
+
+### Replays for Specific Users
+
+You can set up replays to be recorded automatically for a particular user group. Here's an example where we want to record session-based replays for all users who are employees. The `user` object has an `isEmployee` field to signal employee status.
+
+```javascript
+const replay = new Sentry.Replay();
+
+/**
+ * Initialize the Sentry SDK as normal.
+ *
+ * `replaysSessionSampleRate` is set to its default value of "0.1" so that only ~10% of users are sampled
+ * `replaysOnErrorSampleRate` is set to its default value of "1.0" to always record a replay when an error occurs
+ */
+Sentry.init({
+ dsn: "...",
+ replaysSessionSampleRate: 0.1,
+ replaysOnErrorSampleRate: 1.0,
+ integrations: [replay],
+});
+
+// ...
+// After a user has been authenticated, check if they're an employee
+// If they are, we'll call `replay.flush()` to either flush the replay as normal if it's a session-based replay, or if it's buffering due to error sampling, the flush will send the first segment of the replay.
+
+// Since `replaysOnErrorSampleRate` is > 0, we know that a replay has been buffered and `flush()` will flush the contents of that buffer. If only `replaysSessionSampleRate` is > 1, then there is a chance that a replay has not been recording/buffering.
+// In this case, you can check that `replay.getReplayId()` returns a value, if it does, it means replay is active and you can call `replay.flush()`, other call `replay.start()` to start recording a new replay.
+// ...
+
+// Check if user is an employee, if so, always record a replay
+if (loggedInUser.isEmployee) {
+ // You can get a reference to the Sentry Replay integration like so:
+ const replay = Sentry.getCurrentHub().getIntegration(Sentry.Replay);
+ // or alternatively
+ // const replay = Sentry.getCurrentHub().getClient().getIntegrationById('Replay');
+
+ replay.flush();
+}
+```
+
+### Replays on Specific URLs
+
+You can also choose to record a replay every time a user lands on a specified URL. This can help developers debug problematic pages. To do this, use the [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API), which can listen to navigation events for a specific URL and start the replay recording.
+
+```javascript
+const replay = new Sentry.Replay();
+
+/**
+ * Initialize the Sentry SDK as normal.
+ *
+ * `replaysSessionSampleRate` and `replaysOnErrorSampleRate` are both set to
+ * "0" so that we have manual control over session-based replays
+ */
+Sentry.init({
+ dsn: "...",
+ replaysSessionSampleRate: 0,
+ replaysOnErrorSampleRate: 0,
+ integrations: [replay],
+});
+
+// Listen to navigation events for when users land on our buggy URL, appropriately named: "/buggy-page/"
+// and then start recording a replay.
+navigation.addEventListener("navigate", (event) => {
+ const url = new URL(event.destination.url);
+
+ if (url.pathname.startsWith("/buggy-page/")) {
+ // User navigates to the buggy page, let's start recording
+ replay.start();
+ }
+});
+```