Understanding Sessions

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

By default, Replay will immediately start a session when the new Replay() integration instance is added to the SDK client. The session will be in either session or buffer mode, depending on your replaysSessionSampleRate and replaysOnErrorSampleRate.

When Replay is initialized, we check the replaysSessionSampleRate. If it's sampled, we'll start recording and sending Replay data immediately.

If replaysOnErrorSampleRate > 0, we'll start recording in buffering mode and keep checking replaysOnErrorSampleRate whenever an error occurs. Once we see that it's sampled, we'll upload the Replay to Sentry and continue recording normally.

If both replaysSessionSampleRate and replaysOnErrorSampleRate are 0, the recording won't start, but you'll be able to record manually.

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

In buffer mode, Replay will continuously record data, but won't send any of it. It will instead keep up to the last 60 seconds in memory. When an error occurs, replaysOnErrorSampleRate will be checked and if it's sampled, the replay will be uploaded to Sentry and continue recording 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

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.

async function init(sessionSampleRate, errorSampleRate) {
  const client = Sentry.getCurrentHub().getClient();
  const options = client.getOptions();
  options.replaysSessionSampleRate = sessionSampleRate;
  options.replaysOnErrorSampleRate = errorSampleRate;

  const replay = new Sentry.Replay({
    maskAllText: true,
    // additional SDK config, see https://docs.sentry.io/platforms/javascript/session-replay/configuration/
  });

  client.addIntegration(replay);
}

Manually Starting Replay

You can manually start a Replay session with:

// This initializes Replay without starting any session
const replay = new Sentry.Replay();

Sentry.init({
  dsn: "...",
  replaysSessionSampleRate: 0,
  replaysOnErrorSampleRate: 0,
  integrations: [replay],
});

// This starts in `session` mode, regardless of sample rates
replay.start();

// OR

// This starts in `buffer` mode, regardless of sample rates
replay.startBuffering();

This can be used either if both replaysSessionSampleRate and replaysOnErrorSampleRate are 0 and thus no session has been started automatically, or if you previously stopped a session and want to start a new one (see below). start() and startBuffering() will throw an error if a session is currently running.

Manually Stopping Replay

You can always stop a running session with:

await replay.stop();

This will flush any pending recording data, stop the replay, and end the session.

Manually Flushing Recording Data

You can flush any pending recording data with:

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.