--- title: "Understanding Sessions" description: "Learn about customizing sessions with the Session Replay SDK." url: https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions/ --- # Understanding Sessions | Sentry for Next.js In most cases, setting the Replay sample rates will be all you need to do to begin capturing recording data you care about. For more complex cases, it's helpful to understand how sessions work and how to manually control them. ## [Default Session Initialization](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#default-session-initialization) With the `replayIntegration()` enabled in your SDK, a replay session will start capturing based on your sample rate settings: | Configuration | What Happens | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `replaysSessionSampleRate > 0` | Starts in [**session mode**](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#session-mode) | | `replaysOnErrorSampleRate > 0` only | Starts in [**buffer mode**](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#buffer-mode) | | Both rates are `0` | Replay is installed but inactive until you [**manually start it**](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#manually-starting-replay) | **Recommended default:** ```javascript replaysSessionSampleRate: 0.1, // 10% of sessions replaysOnErrorSampleRate: 1.0, // 100% of all errors ``` This captures 10% of sessions in full, plus every error from the remaining 90%. Think of it like a security camera: some cameras always record, others only save footage when the alarm goes off. ## [Session Mode](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#session-mode) In `session` mode, Replay will continuously record and send data to Sentry. After 15 minutes of user inactivity, or a maximum duration of 60 minutes, the session will end and a new session will be initialized based on the rules from the section above. ## [Buffer Mode](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#buffer-mode) In `buffer` mode, Replay will continuously record data, but won't send any of it. It stores the last 60 seconds of event logs in a memory ring buffer (approximately 2-5MB). **What's stored:** Web Session Replay captures lightweight DOM event logs (clicks, scrolls, mutations), not video files. These logs are automatically converted to video-like replays by Sentry's servers. When an error occurs, `replaysOnErrorSampleRate` will be checked and if it's sampled, the buffered 60 seconds *before* the error plus everything *after* is uploaded to Sentry and recording continues normally. After 15 minutes of user inactivity, or a maximum duration of 60 minutes, the session will end and the replay will stop. ## [Manually Add Replay Integration](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#manually-add-replay-integration) It is also possible to defer the initialization and loading of the Replay integration. This is helpful to decouple the SDK initialization from Replay configuration. For example, if you have an external sampling service that is not immediately available. ```javascript async function init(sessionSampleRate, errorSampleRate) { const client = Sentry.getClient(); const options = client.getOptions(); options.replaysSessionSampleRate = sessionSampleRate; options.replaysOnErrorSampleRate = errorSampleRate; const replay = Sentry.replayIntegration({ maskAllText: true, // additional SDK config, see https://docs.sentry.io/platforms/javascript/session-replay/configuration/ }); client.addIntegration(replay); } ``` ## [Manually Starting Replay](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#manually-starting-replay) You can manually start a Replay session with: ```javascript Sentry.init({ dsn: "...", // This initializes Replay without starting any session replaysSessionSampleRate: 0, replaysOnErrorSampleRate: 0, integrations: [Sentry.replayIntegration()], }); // You can access the active replay instance from anywhere in your code like this: const replay = Sentry.getReplay(); // This starts in `session` mode, regardless of sample rates replay.start(); // OR // This starts in `buffer` mode, regardless of sample rates replay.startBuffering(); ``` If both `replaysSessionSampleRate` and `replaysOnErrorSampleRate` are `0`, then you'll need to manually start a session replay, as shown above. This is also useful if you previously stopped a session and want to start a new one (see below). If a session is currently running, `start()` and `startBuffering()` are safe and have no effect. They will [log a debug message](https://docs.sentry.io/platforms/javascript/configuration/options.md#debug) in this case. ## [Manually Stopping Replay](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#manually-stopping-replay) You can always stop a running session with: ```javascript await replay.stop(); ``` This will flush any pending recording data, stop the replay, and end the session. ## [Manually Flushing Recording Data](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#manually-flushing-recording-data) You can flush any pending recording data with: ```javascript 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`. Calling `flush()` while Session Replay is stopped will start a new session recording. ## [Examples of Custom Sampling](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#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](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#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 = Sentry.replayIntegration(); /** * 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 > 0, 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.getReplay(); replay.flush(); } ``` ### [Replays on Specific URLs](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#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 = Sentry.replayIntegration(); /** * 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(); } }); ``` ### [Ignore certain Errors for Error Sampling](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#ignore-certain-errors-for-error-sampling) When using `replaysOnErrorSampleRate`, we "roll the dice" on any Error that is captured & sent to Sentry. If you want to skip capturing a Replay for certain errors, you can use the `beforeErrorSampling` callback: ```javascript replayIntegration({ beforeErrorSampling: (event) => { // Return false to skip capturing a Replay for this error return !event.exception?.values?.[0]?.value?.includes("drop me"); }, }); ``` If you return `false` from this method for a given error, we will not check the error sample rate for this error. If you return `true`, we will continue to check the error sample rate as normal. Note that this hook only runs in `buffer` mode, as `session` mode records continuously regardless of errors. ### [Connect Replays with Support Software](https://docs.sentry.io/platforms/javascript/guides/nextjs/session-replay/understanding-sessions.md#connect-replays-with-support-software) Replays do not need to be connected to an application error, they can also be used to supplement your support tickets. Depending on the level of customization provided by your support widget, it is possible to send a replay to Sentry when your users open the support widget. Note that Sentry's [User Feedback](https://docs.sentry.io/product/user-feedback.md#user-feedback-widget) provides this functionality by default! You can then send the ID of the replay along with the support ticket that your user submits. The ID can be used to reference the replay in Sentry. Alternatively, you can search for replays by a user identifier such as email. The example below provides a template for how you might connect Replay to your support widget. ```javascript /** * Initialize the Sentry SDK as normal. * * `replaysOnErrorSampleRate` needs to be > 0 so that replays are always buffering and only sent when necessary */ Sentry.init({ dsn: "...", replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 0.5, integrations: [Sentry.replayIntegration()], }); /** * Your widget will need to have an event/hook to trigger flushing the replay to * Sentry. */ MySupportWidget.on("open", () => { const replay = Sentry.getReplay(); // Send replay to Sentry replay.flush(); // Retrieve the replay id that was saved and attach it to your support widget const replayId = replay.getReplayId(); MySupportWidget.setTag("replayId", replayId); }); /** * If your support application allows you to send custom data with the support * ticket, you may want to include a link to the replay URL in Sentry. That * way, you'll be able to open the replay directly from the ticket itself. * Replay URLs have the following format: * * https://.sentry.io/replays// * */ ```