Replay

When an SDK records Session Replay in session mode (sessionSampleRate is specified), the recording SHOULD start when the SDK is initialized and MUST be continuously streamed to the Sentry servers. SDKs SHOULD send a replay envelope every 5 seconds.

The maximum duration of the recording MUST NOT exceed 60 minutes (or 15 minutes without activity on Web). (since 1.2.0) After the hard limit has been reached, the SDK MUST stop recording, clear the current replay_id, and remove it from the Scope so all subsequent events are not associated with it.

For SDKs that support disk cache, the recording SHOULD pause when there is no internet connection or the SDK is being rate-limited. This prevents overflowing the disk cache, which can result in losing more critical envelopes. When internet connection is restored or the rate limit is lifted, the recording SHOULD resume.

When an SDK records Session Replay in buffer mode (onErrorSampleRate is specified), the recording SHOULD start when the SDK is initialized and MUST be buffered in-memory (and to disk if the SDK supports disk cache) in a ring buffer for up to 30 seconds back.

Capturing of the recording MAY be triggered when one of the following conditions is met:

• A crash or error event occurs and is captured by the SDK.
• The flush API has been called manually on the replay (for SDKs that support manual API).

After the initial (buffered) segment has been captured, the SDK SHOULD continue recording in session mode. The replay_type field of subsequent segments MUST still be set to buffer to reflect the original replay type.

If the crash or error event has been dropped in beforeSend, the replay MUST NOT be captured.

A replay_event Item MUST always be sent together with a replay_recording Item in the same envelope.

Replay Attributes

Event Attributes

The following attributes are a subset of the optional attributes of an Event.

The replay_recording item consists of two sub-items delimited by a newline:

1. Metadata — a JSON object. Currently only segment_id is required:

{ "segment_id": 0 }

2. Recording payload — the replay recording instruction set. This payload SHOULD be gzipped, but uncompressed payloads are also accepted. See Replay Recording Events for the recording format.

SDKs MUST accept a replaysSessionSampleRate configuration option (number, 0.0–1.0, default 0). This controls the fraction of sessions recorded in session mode. 1.0 records all sessions, 0 records none.

Naming SHOULD follow the SDK's language conventions:

• replaysSessionSampleRate (JavaScript)
• replays_session_sample_rate (Python)

SDKs MUST accept a replaysOnErrorSampleRate configuration option (number, 0.0–1.0, default 0). This controls the fraction of sessions buffered for error replay. 1.0 captures all sessions with an error, 0 captures none.

Naming SHOULD follow the SDK's language conventions:

• replaysOnErrorSampleRate (JavaScript)
• replays_on_error_sample_rate (Python)

SDKs MUST provide a replay integration that initializes the recording subsystem:

replayIntegration(options?) -> Integration

SDKs MAY accept privacy and configuration options (text masking, media blocking, network capture settings).

Naming SHOULD follow the SDK's language conventions:

• replayIntegration() (JavaScript)
• SessionReplayIntegration() (Python)
• SentryReplay / SessionReplay (mobile SDKs)

SDKs SHOULD expose a function to retrieve the active replay instance:

getReplay() -> replayInstance | null

Returns the replay integration instance if replay is initialized, or null if not. The returned instance provides the runtime control methods documented below.

The replay instance MUST expose a method to retrieve the current replay identifier:

replayInstance.getReplayId() -> replayId | null

Returns the current replay_id (string) if a replay is active, or null if no replay is recording or buffering. This is useful for checking whether a replay is active before calling other runtime methods.

The replay instance SHOULD expose a method to manually start recording in session mode:

replayInstance.start() -> void

Starts recording in session mode regardless of sample rates. If a session is already running, this SHOULD be a no-op.

The replay instance SHOULD expose a method to manually start recording in buffer mode:

replayInstance.startBuffering() -> void

Starts recording in buffer mode regardless of sample rates. If a session is already running, this SHOULD be a no-op.

The replay instance SHOULD expose a method to stop recording:

replayInstance.stop() -> Promise<void>

Flushes any pending recording data, stops the replay, and ends the session.

The replay instance SHOULD expose a method to flush pending recording data:

replayInstance.flush() -> Promise<void>

In session mode, this uploads pending recording data to Sentry. In buffer mode, this uploads the buffered data and continues recording (same as when an error triggers capture). Calling flush() while replay is stopped MAY start a new session recording.