From c492abbee3164829c3a8466d25ae5d41b3a57bfc Mon Sep 17 00:00:00 2001 From: Billy Vong Date: Tue, 24 Oct 2023 12:41:34 -0400 Subject: [PATCH] feat(replay): Add examples for custom sampling (#8035) * feat(replay): Add examples for custom sampling Give more specific example scenarios for custom sampling. Closes https://github.com/getsentry/sentry-docs/issues/7839 * style(lint): Auto commit lint changes * Apply suggestions from code review Co-authored-by: Liza Mock * update examples * Update src/platforms/javascript/common/session-replay/understanding-sessions.mdx Co-authored-by: Liza Mock * Update index.mdx (#7994) * Update index.mdx (#8032) Co-authored-by: Shana Matthews * updates * Apply suggestions from code review Co-authored-by: Francesco Novy * continue to record replay instead of stop --------- Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com> Co-authored-by: Liza Mock Co-authored-by: JGS3089 <145158937+JGS3089@users.noreply.github.com> Co-authored-by: Shana Matthews Co-authored-by: Francesco Novy --- .../session-replay/understanding-sessions.mdx | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/src/platforms/javascript/common/session-replay/understanding-sessions.mdx b/src/platforms/javascript/common/session-replay/understanding-sessions.mdx index ac35275e616bf..ee15af360d977 100644 --- a/src/platforms/javascript/common/session-replay/understanding-sessions.mdx +++ b/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(); + } +}); +```