feat(replay): Add replayStart/replayEnd client lifecycle hooks (#20369)

Expose replay lifecycle events on the client so external consumers can
observe when recording starts and stops.

This includes internal stops (session expiry, send errors, mutation
limit, event buffer overflow) that today are invisible to wrapper
libraries.

Closes #20281.

## API

```ts
getClient()?.on('replayStart', ({ sessionId, recordingMode }) => {
  // recordingMode: 'session' | 'buffer'
});

getClient()?.on('replayEnd', ({ sessionId, reason }) => {
  // reason: 'manual' | 'sessionExpired' | 'sendError' | 'mutationLimit'
  //       | 'eventBufferError' | 'eventBufferOverflow'
});
```

The typed `reason` union lets consumers distinguish a user-initiated
`replay.stop()` from an internally triggered stop, so wrapper state can
stay in sync with actual replay state.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: logaretm

packages/core/src/client.ts

@@ -28,6 +28,7 @@ import type { Metric } from './types-hoist/metric';
 import type { Primitive } from './types-hoist/misc';
 import type { ClientOptions } from './types-hoist/options';
 import type { ParameterizedString } from './types-hoist/parameterize';
+import type { ReplayEndEvent, ReplayStartEvent } from './types-hoist/replay';
 import type { RequestEventData } from './types-hoist/request';
 import type { SdkMetadata } from './types-hoist/sdkmetadata';
 import type { Session, SessionAggregates } from './types-hoist/session';
@@ -726,6 +727,19 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
    */
   public on(hook: 'openFeedbackWidget', callback: () => void): () => void;
 
+  /**
+   * A hook that is called when a replay session starts recording (either session or buffer mode).
+   * @returns {() => void} A function that, when executed, removes the registered callback.
+   */
+  public on(hook: 'replayStart', callback: (event: ReplayStartEvent) => void): () => void;
+
+  /**
+   * A hook that is called when a replay session stops recording, either manually or due to an
+   * internal condition such as `maxReplayDuration` expiry, send failure, or mutation limit.
+   * @returns {() => void} A function that, when executed, removes the registered callback.
+   */
+  public on(hook: 'replayEnd', callback: (event: ReplayEndEvent) => void): () => void;
+
   /**
    * A hook for the browser tracing integrations to trigger a span start for a page load.
    * @returns {() => void} A function that, when executed, removes the registered callback.
@@ -1001,6 +1015,16 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
    */
   public emit(hook: 'openFeedbackWidget'): void;
 
+  /**
+   * Fire a hook event when a replay session starts recording.
+   */
+  public emit(hook: 'replayStart', event: ReplayStartEvent): void;
+
+  /**
+   * Fire a hook event when a replay session stops recording.
+   */
+  public emit(hook: 'replayEnd', event: ReplayEndEvent): void;
+
   /**
    * Emit a hook event for browser tracing integrations to trigger a span start for a page load.
    */

packages/core/src/index.ts

@@ -441,7 +441,14 @@ export type {
   Profile,
   ProfileChunk,
 } from './types-hoist/profiling';
-export type { ReplayEvent, ReplayRecordingData, ReplayRecordingMode } from './types-hoist/replay';
+export type {
+  ReplayEndEvent,
+  ReplayEvent,
+  ReplayRecordingData,
+  ReplayRecordingMode,
+  ReplayStartEvent,
+  ReplayStopReason,
+} from './types-hoist/replay';
 export type {
   FeedbackEvent,
   FeedbackFormData,

packages/core/src/types-hoist/replay.ts

@@ -25,3 +25,37 @@ export type ReplayRecordingData = string | Uint8Array;
  * @hidden
  */
 export type ReplayRecordingMode = 'session' | 'buffer';
+
+/**
+ * Reason a replay recording stopped, passed to the `replayEnd` client hook.
+ *
+ * - `manual`: user called `replay.stop()`.
+ * - `sessionExpired`: session hit `maxReplayDuration` or the idle-expiry threshold.
+ * - `sendError`: a replay segment failed to send after retries.
+ * - `mutationLimit`: DOM mutation budget for the session was exhausted.
+ * - `eventBufferError`: the event buffer threw an unexpected error.
+ * - `eventBufferOverflow`: the event buffer ran out of space.
+ */
+export type ReplayStopReason =
+  | 'manual'
+  | 'sessionExpired'
+  | 'sendError'
+  | 'mutationLimit'
+  | 'eventBufferError'
+  | 'eventBufferOverflow';
+
+/**
+ * Payload emitted on the `replayStart` client hook when a replay begins recording.
+ */
+export interface ReplayStartEvent {
+  sessionId: string;
+  recordingMode: ReplayRecordingMode;
+}
+
+/**
+ * Payload emitted on the `replayEnd` client hook when a replay stops recording.
+ */
+export interface ReplayEndEvent {
+  sessionId?: string;
+  reason: ReplayStopReason;
+}

packages/replay-internal/src/integration.ts

@@ -297,7 +297,7 @@ export class Replay implements Integration {
       return Promise.resolve();
     }
 
-    return this._replay.stop({ forceFlush: this._replay.recordingMode === 'session' });
+    return this._replay.stop({ forceFlush: this._replay.recordingMode === 'session', reason: 'manual' });
   }
 
   /**

packages/replay-internal/src/replay.ts

@@ -1,5 +1,5 @@
 /* eslint-disable max-lines */ // TODO: We might want to split this file up
-import type { ReplayRecordingMode, Span } from '@sentry/core';
+import type { ReplayRecordingMode, ReplayStopReason, Span } from '@sentry/core';
 import { getActiveSpan, getClient, getRootSpan, SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, spanToJSON } from '@sentry/core';
 import { EventType, record } from '@sentry-internal/rrweb';
 import {
@@ -495,7 +495,10 @@ export class ReplayContainer implements ReplayContainerInterface {
    * Currently, this needs to be manually called (e.g. for tests). Sentry SDK
    * does not support a teardown
    */
-  public async stop({ forceFlush = false, reason }: { forceFlush?: boolean; reason?: string } = {}): Promise<void> {
+  public async stop({
+    forceFlush = false,
+    reason,
+  }: { forceFlush?: boolean; reason?: ReplayStopReason } = {}): Promise<void> {
     if (!this._isEnabled) {
       return;
     }
@@ -508,8 +511,11 @@ export class ReplayContainer implements ReplayContainerInterface {
     // breadcrumbs to trigger a flush (e.g. in `addUpdate()`)
     this.recordingMode = 'buffer';
 
+    const stopReason: ReplayStopReason = reason ?? 'manual';
+    getClient()?.emit('replayEnd', { sessionId: this.session?.id, reason: stopReason });
+
     try {
-      DEBUG_BUILD && debug.log(`Stopping Replay${reason ? ` triggered by ${reason}` : ''}`);
+      DEBUG_BUILD && debug.log(`Stopping Replay triggered by ${stopReason}`);
 
       resetReplayIdOnDynamicSamplingContext();
 
@@ -862,6 +868,13 @@ export class ReplayContainer implements ReplayContainerInterface {
     this._isEnabled = true;
     this._isPaused = false;
 
+    if (this.session) {
+      getClient()?.emit('replayStart', {
+        sessionId: this.session.id,
+        recordingMode: this.recordingMode,
+      });
+    }
+
     this.startRecording();
   }
 
@@ -926,7 +939,7 @@ export class ReplayContainer implements ReplayContainerInterface {
     if (!this._isEnabled) {
       return;
     }
-    await this.stop({ reason: 'refresh session' });
+    await this.stop({ reason: 'sessionExpired' });
     this.initializeSampling(session.id);
   }
 
@@ -1212,7 +1225,7 @@ export class ReplayContainer implements ReplayContainerInterface {
       // In this case, we want to completely stop the replay - otherwise, we may get inconsistent segments
       // This should never reject
       // eslint-disable-next-line @typescript-eslint/no-floating-promises
-      this.stop({ reason: 'sendReplay' });
+      this.stop({ reason: 'sendError' });
 
       const client = getClient();
 

packages/replay-internal/src/types/replay.ts

@@ -1,4 +1,11 @@
-import type { Breadcrumb, ErrorEvent, ReplayRecordingData, ReplayRecordingMode, Span } from '@sentry/core';
+import type {
+  Breadcrumb,
+  ErrorEvent,
+  ReplayRecordingData,
+  ReplayRecordingMode,
+  ReplayStopReason,
+  Span,
+} from '@sentry/core';
 import type { SKIPPED, THROTTLED } from '../util/throttle';
 import type { AllPerformanceEntry, AllPerformanceEntryData, ReplayPerformanceEntry } from './performance';
 import type { ReplayFrameEvent } from './replayFrame';
@@ -507,7 +514,7 @@ export interface ReplayContainer {
   getContext(): InternalEventContext;
   initializeSampling(): void;
   start(): void;
-  stop(options?: { reason?: string; forceflush?: boolean }): Promise<void>;
+  stop(options?: { reason?: ReplayStopReason; forceFlush?: boolean }): Promise<void>;
   pause(): void;
   resume(): void;
   startRecording(): void;

packages/replay-internal/src/util/addEvent.ts

@@ -82,7 +82,7 @@ async function _addEvent(
     return await eventBuffer.addEvent(eventAfterPossibleCallback);
   } catch (error) {
     const isExceeded = error && error instanceof EventBufferSizeExceededError;
-    const reason = isExceeded ? 'addEventSizeExceeded' : 'addEvent';
+    const reason = isExceeded ? 'eventBufferOverflow' : 'eventBufferError';
     const client = getClient();
 
     if (client) {

packages/replay-internal/test/integration/lifecycleHooks.test.ts

@@ -0,0 +1,109 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import '../utils/mock-internal-setTimeout';
+import type { ReplayEndEvent, ReplayStartEvent } from '@sentry/core';
+import { getClient } from '@sentry/core';
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Replay } from '../../src/integration';
+import type { ReplayContainer } from '../../src/replay';
+import { BASE_TIMESTAMP } from '../index';
+import { resetSdkMock } from '../mocks/resetSdkMock';
+
+describe('Integration | lifecycle hooks', () => {
+  let replay: ReplayContainer;
+  let integration: Replay;
+  let startEvents: ReplayStartEvent[];
+  let endEvents: ReplayEndEvent[];
+  let unsubscribes: Array<() => void>;
+
+  beforeAll(() => {
+    vi.useFakeTimers();
+  });
+
+  beforeEach(async () => {
+    ({ replay, integration } = await resetSdkMock({
+      replayOptions: { stickySession: false },
+      sentryOptions: { replaysSessionSampleRate: 0.0 },
+      autoStart: false,
+    }));
+
+    startEvents = [];
+    endEvents = [];
+    const client = getClient()!;
+    unsubscribes = [
+      client.on('replayStart', event => startEvents.push(event)),
+      client.on('replayEnd', event => endEvents.push(event)),
+    ];
+
+    await vi.runAllTimersAsync();
+  });
+
+  afterEach(async () => {
+    unsubscribes.forEach(off => off());
+    await integration.stop();
+    await vi.runAllTimersAsync();
+    vi.setSystemTime(new Date(BASE_TIMESTAMP));
+  });
+
+  it('fires replayStart with session mode when start() is called', () => {
+    integration.start();
+
+    expect(startEvents).toHaveLength(1);
+    expect(startEvents[0]).toEqual({
+      sessionId: expect.any(String),
+      recordingMode: 'session',
+    });
+    expect(startEvents[0]!.sessionId).toBe(replay.session!.id);
+  });
+
+  it('fires replayStart with buffer mode when startBuffering() is called', () => {
+    integration.startBuffering();
+
+    expect(startEvents).toHaveLength(1);
+    expect(startEvents[0]).toEqual({
+      sessionId: expect.any(String),
+      recordingMode: 'buffer',
+    });
+  });
+
+  it('fires replayEnd with reason "manual" when integration.stop() is called', async () => {
+    integration.start();
+    const sessionId = replay.session!.id;
+
+    await integration.stop();
+
+    expect(endEvents).toHaveLength(1);
+    expect(endEvents[0]).toEqual({ sessionId, reason: 'manual' });
+  });
+
+  it('forwards the internal stop reason to replayEnd subscribers', async () => {
+    integration.start();
+    const sessionId = replay.session!.id;
+
+    await replay.stop({ reason: 'mutationLimit' });
+
+    expect(endEvents).toHaveLength(1);
+    expect(endEvents[0]).toEqual({ sessionId, reason: 'mutationLimit' });
+  });
+
+  it('does not fire replayEnd twice when stop() is called while already stopped', async () => {
+    integration.start();
+
+    await replay.stop({ reason: 'sendError' });
+    await replay.stop({ reason: 'sendError' });
+
+    expect(endEvents).toHaveLength(1);
+    expect(endEvents[0]!.reason).toBe('sendError');
+  });
+
+  it('stops invoking callbacks after the returned unsubscribe is called', () => {
+    const [offStart] = unsubscribes;
+    offStart!();
+
+    integration.start();
+
+    expect(startEvents).toHaveLength(0);
+  });
+});