feat(replay): Change flush() API to record current event buffer (#7743)

This adds a public API: `capture` that will record the current event buffer and by default, convert the replay type to "session" and continue recording. We have extracted the logic that was used for "onError" capturing and made it a public API.

Author: billyvg

packages/replay/src/coreHandlers/handleAfterSendEvent.ts

@@ -53,19 +53,9 @@ export function handleAfterSendEvent(replay: ReplayContainer): AfterSendEventCal
       event.exception &&
       event.message !== UNABLE_TO_SEND_REPLAY // ignore this error because otherwise we could loop indefinitely with trying to capture replay and failing
     ) {
-      setTimeout(async () => {
-        // Allow flush to complete before resuming as a session recording, otherwise
-        // the checkout from `startRecording` may be included in the payload.
-        // Prefer to keep the error replay as a separate (and smaller) segment
-        // than the session replay.
-        await replay.flushImmediate();
-
-        if (replay.stopRecording()) {
-          // Reset all "capture on error" configuration before
-          // starting a new recording
-          replay.recordingMode = 'session';
-          replay.startRecording();
-        }
+      setTimeout(() => {
+        // Capture current event buffer as new replay
+        void replay.sendBufferedReplayOrFlush();
       });
     }
   };

packages/replay/src/integration.ts

@@ -4,7 +4,7 @@ import { dropUndefinedKeys } from '@sentry/utils';
 
 import { DEFAULT_FLUSH_MAX_DELAY, DEFAULT_FLUSH_MIN_DELAY } from './constants';
 import { ReplayContainer } from './replay';
-import type { RecordingOptions, ReplayConfiguration, ReplayPluginOptions } from './types';
+import type { RecordingOptions, ReplayConfiguration, ReplayPluginOptions, SendBufferedReplayOptions } from './types';
 import { getPrivacyOptions } from './util/getPrivacyOptions';
 import { isBrowser } from './util/isBrowser';
 
@@ -216,14 +216,18 @@ Sentry.init({ replaysOnErrorSampleRate: ${errorSampleRate} })`,
   }
 
   /**
-   * Immediately send all pending events.
+   * Immediately send all pending events. In buffer-mode, this should be used
+   * to capture the initial replay.
+   *
+   * Unless `continueRecording` is false, the replay will continue to record and
+   * behave as a "session"-based replay.
    */
-  public flush(): Promise<void> | void {
+  public flush(options?: SendBufferedReplayOptions): Promise<void> | void {
     if (!this._replay || !this._replay.isEnabled()) {
       return;
     }
 
-    return this._replay.flushImmediate();
+    return this._replay.sendBufferedReplayOrFlush(options);
   }
 
   /**

packages/replay/src/replay.ts

@@ -20,6 +20,7 @@ import type {
   ReplayContainer as ReplayContainerInterface,
   ReplayExperimentalPluginOptions,
   ReplayPluginOptions,
+  SendBufferedReplayOptions,
   Session,
   Timeouts,
 } from './types';
@@ -230,17 +231,18 @@ export class ReplayContainer implements ReplayContainerInterface {
 
   /**
    * Stops the recording, if it was running.
-   * Returns true if it was stopped, else false.
+   *
+   * Returns true if it was previously stopped, or is now stopped,
+   * otherwise false.
    */
   public stopRecording(): boolean {
     try {
       if (this._stopRecording) {
         this._stopRecording();
         this._stopRecording = undefined;
-        return true;
       }
 
-      return false;
+      return true;
     } catch (err) {
       this._handleException(err);
       return false;
@@ -303,6 +305,38 @@ export class ReplayContainer implements ReplayContainerInterface {
     this.startRecording();
   }
 
+  /**
+   * If not in "session" recording mode, flush event buffer which will create a new replay.
+   * Unless `continueRecording` is false, the replay will continue to record and
+   * behave as a "session"-based replay.
+   *
+   * Otherwise, queue up a flush.
+   */
+  public async sendBufferedReplayOrFlush({ continueRecording = true }: SendBufferedReplayOptions = {}): Promise<void> {
+    if (this.recordingMode === 'session') {
+      return this.flushImmediate();
+    }
+
+    // Allow flush to complete before resuming as a session recording, otherwise
+    // the checkout from `startRecording` may be included in the payload.
+    // Prefer to keep the error replay as a separate (and smaller) segment
+    // than the session replay.
+    await this.flushImmediate();
+
+    const hasStoppedRecording = this.stopRecording();
+
+    if (!continueRecording || !hasStoppedRecording) {
+      return;
+    }
+
+    // Re-start recording, but in "session" recording mode
+
+    // Reset all "capture on error" configuration before
+    // starting a new recording
+    this.recordingMode = 'session';
+    this.startRecording();
+  }
+
   /**
    * We want to batch uploads of replay events. Save events only if
    * `<flushMinDelay>` milliseconds have elapsed since the last event

packages/replay/src/types.ts

@@ -446,6 +446,10 @@ export interface EventBuffer {
 
 export type AddUpdateCallback = () => boolean | void;
 
+export interface SendBufferedReplayOptions {
+  continueRecording?: boolean;
+}
+
 export interface ReplayContainer {
   eventBuffer: EventBuffer | null;
   performanceEvents: AllPerformanceEntry[];
@@ -464,7 +468,8 @@ export interface ReplayContainer {
   resume(): void;
   startRecording(): void;
   stopRecording(): boolean;
-  flushImmediate(): void;
+  sendBufferedReplayOrFlush(options?: SendBufferedReplayOptions): Promise<void>;
+  flushImmediate(): Promise<void>;
   triggerUserActivity(): void;
   addUpdate(cb: AddUpdateCallback): void;
   getOptions(): ReplayPluginOptions;

packages/replay/test/integration/errorSampleRate.test.ts

@@ -158,6 +158,100 @@ describe('Integration | errorSampleRate', () => {
     });
   });
 
+  it('manually flushes replay and does not continue to record', async () => {
+    const TEST_EVENT = { data: {}, timestamp: BASE_TIMESTAMP, type: 3 };
+    mockRecord._emitter(TEST_EVENT);
+
+    expect(mockRecord.takeFullSnapshot).not.toHaveBeenCalled();
+    expect(replay).not.toHaveLastSentReplay();
+
+    // Does not capture on mouse click
+    domHandler({
+      name: 'click',
+    });
+    jest.runAllTimers();
+    await new Promise(process.nextTick);
+    expect(replay).not.toHaveLastSentReplay();
+
+    replay.sendBufferedReplayOrFlush({ continueRecording: false });
+
+    await new Promise(process.nextTick);
+    jest.advanceTimersByTime(DEFAULT_FLUSH_MIN_DELAY);
+    await new Promise(process.nextTick);
+
+    expect(replay).toHaveSentReplay({
+      recordingPayloadHeader: { segment_id: 0 },
+      replayEventPayload: expect.objectContaining({
+        replay_type: 'error',
+        contexts: {
+          replay: {
+            error_sample_rate: 1,
+            session_sample_rate: 0,
+          },
+        },
+      }),
+      recordingData: JSON.stringify([
+        { data: { isCheckout: true }, timestamp: BASE_TIMESTAMP, type: 2 },
+        TEST_EVENT,
+        {
+          type: 5,
+          timestamp: BASE_TIMESTAMP,
+          data: {
+            tag: 'breadcrumb',
+            payload: {
+              timestamp: BASE_TIMESTAMP / 1000,
+              type: 'default',
+              category: 'ui.click',
+              message: '<unknown>',
+              data: {},
+            },
+          },
+        },
+      ]),
+    });
+
+    jest.advanceTimersByTime(DEFAULT_FLUSH_MIN_DELAY);
+    // Check that click will not get captured
+    domHandler({
+      name: 'click',
+    });
+    jest.advanceTimersByTime(DEFAULT_FLUSH_MIN_DELAY);
+    await new Promise(process.nextTick);
+
+    // This is still the last replay sent since we passed `continueRecording:
+    // false`.
+    expect(replay).toHaveLastSentReplay({
+      recordingPayloadHeader: { segment_id: 0 },
+      replayEventPayload: expect.objectContaining({
+        replay_type: 'error',
+        contexts: {
+          replay: {
+            error_sample_rate: 1,
+            session_sample_rate: 0,
+          },
+        },
+      }),
+      recordingData: JSON.stringify([
+        { data: { isCheckout: true }, timestamp: BASE_TIMESTAMP, type: 2 },
+        TEST_EVENT,
+        {
+          type: 5,
+          timestamp: BASE_TIMESTAMP,
+          data: {
+            tag: 'breadcrumb',
+            payload: {
+              timestamp: BASE_TIMESTAMP / 1000,
+              type: 'default',
+              category: 'ui.click',
+              message: '<unknown>',
+              data: {},
+            },
+          },
+        },
+      ]),
+    });
+  });
+
   it('does not send a replay when triggering a full dom snapshot when document becomes visible after [SESSION_IDLE_DURATION]ms', async () => {
     Object.defineProperty(document, 'visibilityState', {
       configurable: true,