Replays

This document defines the format used by Sentry to ingest replays. This document is meant for Sentry SDK developers and maintainers of the Session Replay ingestion pipeline.

A "replay_event" Item should always be sent with a "replay_recording" Item in the same envelope.

The following attributes are specific to the "replay_event" Item type.

Key	Type	Description
type	`"replay_event"`	Must be `"replay_event"`
replay_id	string	A unique ID for the replay. Follows the same requirements as an `event_id`: Hexadecimal string representing a uuid4 value. The length is exactly 32 characters. Dashes are not allowed. Has to be lowercase.
replay_type	`"session"` \| `"buffer"`	Describes the type of replay. `buffer` means the replay is buffered while waiting for an error to occur or until a manual flush. `session` means the replay starts recording immediately and continues through the lifespan of the replay session.
segment_id	number	The segment id.
replay_start_timestamp	number	UNIX timestamp of the start of the replay (in seconds). This is only required on the first segment.
urls	list[string]	List of URLs in order of visitation.
trace_ids	list[string]	List of trace ids that occurred during the replay.
error_ids	list[string]	DEPRECATED

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

Key	Type	Description
timestamp	number	UNIX timestamp of the current time (in seconds).
event_id	string	This should be the same as `replay_id`
dist	string	-
platform	string	-
environment	string	-
release	string	-
user.id	string	-
user.username	string	-
user.email	string	-
user.ip_address	string	-
sdk.name	string	-
sdk.version	string	-
request.url	string	-
request.headers.User-Agent	string	-

Copied

{
  "type": "replay_event",
  "replay_id": "36b75d9fa11f45459412a96c41bdf691",
  "replay_start_timestamp": 1710861499.287,
  "replay_type": "session",
  "segment_id": 0,
  "trace_ids": ["905aef2282af5fe2ab2c93aa7a340521"],
  "urls": [
    "https://sentry.io/issues/",
    "https://sentry.io/issues/?project=0&statsPeriod=7d&utc=true"
  ],

  "request": {
    "url": "https://sentry.io/issues/?project=0&statsPeriod=7d&utc=true",
    "headers": {
      "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36"
    }
  },
  "timestamp": 1710861507.579,
  "event_id": "36b75d9fa11f45459412a96c41bdf691",
  "environment": "prod",
  "release": "frontend@f00",
  "sdk": {
    "integrations": [
      "BrowserTracing",
      "BrowserProfiling",
      "Replay",
      "ReplayCanvas"
    ],
    "name": "sentry.javascript.react",
    "version": "7.105.0"
  },
  "tags": {
    "sentry_version": "24.4.0.dev0"
  },
  "user": {
    "ip_address": "127.0.0.1",
    "email": "admin@sentry.io",
    "id": 1,
    "name": "Admin"
  },
  "contexts": { "organization": { "id": "0", "slug": "sentry" } },
  "platform": "javascript"
}

The "replay_recording" item consists of two sub-items that are delimited by newlines. The first is a JSON of the replay recording's metadata. Currently, only segment_id is required.

Copied

{ "segment_id": 0 }

The other sub-item is the replay recording's instructions set. This payload should be gzipped, but uncompressed payloads are also accepted. Read more about replay recording events here.

Copied

[
  {
    "type": 5,
    "timestamp": 1710861507579,
    "data": {}
  }
]

Copied

{"segment_id": 0}
\x00\x00\x00\x14ftypqt  \x00\x00\x00\x00qt  \x00\x00\x00\x08wide\x03\xbdd\x11mdat

Copied

{"event_id":"36b75d9fa11f45459412a96c41bdf691","sent_at":"2024-03-19T15:18:27.581Z","sdk":{"name":"sentry.javascript.react","version":"7.105.0"}}
{"type":"replay_event"}
{
  "type": "replay_event",
  "replay_id": "36b75d9fa11f45459412a96c41bdf691",
  "replay_start_timestamp": 1710861499.287,
  "replay_type": "session",
  "segment_id": 0,
  "trace_ids": ["905aef2282af5fe2ab2c93aa7a340521"],
  "urls": [
    "https://sentry.io/issues/",
    "https://sentry.io/issues/?project=0&statsPeriod=7d&utc=true"
  ],

  "request": {
    "url": "https://sentry.io/issues/?project=0&statsPeriod=7d&utc=true",
    "headers": {
      "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36"
    }
  },
  "timestamp": 1710861507.579,
  "event_id": "36b75d9fa11f45459412a96c41bdf691",
  "environment": "prod",
  "release": "frontend@f00",
  "sdk": {
    "integrations": [
      "BrowserTracing",
      "BrowserProfiling",
      "Replay",
      "ReplayCanvas"
    ],
    "name": "sentry.javascript.react",
    "version": "7.105.0"
  },
  "tags": {
    "sentry_version": "24.4.0.dev0",
  },
  "user": {
    "ip_address": "127.0.0.1",
    "email": "admin@sentry.io",
    "id": 1,
    "name": "Admin"
  },
  "contexts": { "organization": { "id": "0", "slug": "sentry" } },
  "platform": "javascript"
}
{"type":"replay_recording","length":141666}
{"segment_id":0}
/* gzipped JSON payload */

When an SDK records Session Replay in session mode (sessionSampleRate is specified), the recording should start when the SDK is initialized and should be continuously streamed to the Sentry servers. The SDK should send a replay envelope every 5 seconds. The maximum duration of the recording should not exceed 60 minutes (or 15 minutes without an activity on Web). After the hard limit has been reached, the SDK should stop recording, clear out the current replay_id and remove it from the Scope so all of the subsequent events don't get associated with it.

For the SDKs that support disk cache, the recording should pause when there's no internet connection or the SDK is getting rate-limited. This is necessary to prevent overflowing the disk cache, which can potentially result in losing more critical envelopes. When internet connection is restored or 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 should be buffered in-memory (and to disk if the SDK supports disk cache) in a ring buffer for up to 30 seconds back. The 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
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. Note, however, that the replay_type field of the following segments should still be set to buffer to reflect the original replay_type.

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

Profiles

Sessions

Was this helpful?

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").

How to contribute | Edit this page | Create a docs issue | Get support