Skip to content
This repository was archived by the owner on Aug 14, 2024. It is now read-only.

Commit c00863b

Browse files
billyvgbillyvg
authored
feat(replay): Add documentation about replay event types (#1197)
Relates to: * #1144
1 parent 5abf76a commit c00863b

File tree

4 files changed

+423
-0
lines changed

4 files changed

+423
-0
lines changed

‎src/components/sidebar.tsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,7 @@ export default () => {
226226
<SidebarLink to="/sdk/event-payloads/user/">User Interface</SidebarLink>
227227
</SidebarLink>
228228
<SidebarLink to="/sdk/profiles/">Profiles</SidebarLink>
229+
<SidebarLink to="/sdk/replays/">Replays</SidebarLink>
229230
<SidebarLink to="/sdk/metrics/">Metrics</SidebarLink>
230231
<SidebarLink to="/sdk/check-ins/">Check-Ins</SidebarLink>
231232
<SidebarLink to="/sdk/sessions/">Sessions</SidebarLink>

‎src/docs/sdk/envelopes.mdx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -537,6 +537,48 @@ details.
537537

538538
*None*
539539

540+
### Replay Event
541+
542+
Item type `"replay_event"` contains a replay payload encoded in JSON.
543+
544+
See the <Link to="/sdk/replays/">replays</Link> documentation for the payload
545+
details.
546+
547+
**Constraints:**
548+
549+
- This Item may occur at most once per Envelope.
550+
- This Item must be sent with a Replay Recording Item.
551+
552+
**Envelope Headers:**
553+
554+
*None*
555+
556+
**Additional Item Headers:**
557+
558+
*None*
559+
560+
### Replay Recording
561+
562+
Item type `"replay_recording"` contains a replay recording payload encoded in JSON *or* a gzipped JSON.
563+
564+
See the <Link to="/sdk/replays/">replays</Link> documentation for the payload
565+
details.
566+
567+
**Constraints:**
568+
569+
- This Item may occur at most once per Envelope.
570+
- This Item must be sent with a Replay Recording Item.
571+
572+
**Envelope Headers:**
573+
574+
*None*
575+
576+
**Additional Item Headers:**
577+
578+
`length`
579+
580+
: **integer, required.** The size of the Replay recording payload
581+
540582
### Profile
541583

542584
Item type `"profile"`. This Item contains a profile payload encoded

‎src/docs/sdk/event-payloads/replay-recording.mdx‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
title: Replay Recordings
3+
---
4+
5+
A replay recording consists of a list of instructions for the replayer to play back for the viewer. This page aims to document the custom events that are used on top of the events provided by [rrweb](https://github.com/rrweb-io/rrweb), the recording library that powers Session Replay.
6+
7+
The recording event is an object with the following required properties:
8+
9+
`type`
10+
11+
: **EventTypeEnum** The `type` describes what type of event it is. See the enum below.
12+
13+
```
14+
EventTypeEnum {
15+
DomContentLoaded,
16+
Load,
17+
FullSnapshot,
18+
IncrementalSnapshot,
19+
Meta,
20+
Custom,
21+
Plugin,
22+
}
23+
```
24+
25+
`timestamp`
26+
27+
: **float** The timestamp (in milliseconds) at which the event occurs
28+
29+
`data`
30+
31+
: **unknown** `data` schema is dependent on the `type`. View the [base types](https://github.com/rrweb-io/rrweb/blob/master/packages/types/src/index.ts) or Sentry's [custom types](https://github.com/getsentry/sentry-javascript/blob/master/packages/replay-internal/src/types/replayFrame.ts).
32+
33+
## Custom Events
34+
35+
Sentry custom events augment the replay with additional context in order to help the user debug issues. Custom events have the following format for the `data` property of the event:
36+
37+
`tag`
38+
39+
: **string** The tag is used to describe the "type" of custom event. This will determine how the event gets used in the UI.
40+
41+
`payload`
42+
43+
: **object** The `payload` is similar to the upper level `data` attribute, whose schema is dependent on the `tag`.
44+
45+
In addition to the TypeScript references linked above, the following sections will describe the expected `payload` for custom events.
46+
47+
### options
48+
49+
This recording event is used to record the SDK configuration options. This should only be sent on the first segment as we do not expect the options to change throughout the lifecycle of a replay. See [this issue](https://github.com/getsentry/sentry-javascript/issues/7140) for more context around the decision to send this as a recording event rather than part of the `"replay_event"`. Note that these options are generally used internally to debug rather than a customer-facing feature (e.g. there is no way to query/filter replays using these options).
50+
51+
The payload for `"options"` is a record of configuration name -> configuration value. There is no defined schema as options can vary by SDKs.
52+
53+
```json
54+
{
55+
"type": 5,
56+
"timestamp": 1709218280301,
57+
"data": {
58+
"tag": "options",
59+
"payload": {
60+
"shouldRecordCanvas": false,
61+
"sessionSampleRate": 1,
62+
"errorSampleRate": 1,
63+
"useCompressionOption": true,
64+
"blockAllMedia": false,
65+
"maskAllText": false,
66+
"maskAllInputs": false,
67+
"useCompression": false,
68+
"networkDetailHasUrls": false,
69+
"networkCaptureBodies": true,
70+
"networkRequestHasHeaders": true,
71+
"networkResponseHasHeaders": true
72+
}
73+
}
74+
}
75+
```
76+
77+
### breadcrumb
78+
79+
Breadcrumbs are named as such because they are intercepted from the web SDK and forwarded as a custom recording event. They have the same structure as describe in <Link to="/sdk/event-payloads/breadcrumbs/">breadcrumbs interface</Link>.
80+
81+
```json
82+
{
83+
"type": 5,
84+
"timestamp": 1710853999781,
85+
"data": {
86+
"tag": "breadcrumb",
87+
"payload": {
88+
"timestamp": 1710853999.781,
89+
"type": "default",
90+
"category": "navigation",
91+
"data": {
92+
"from": "/issues/4893218638/",
93+
"to": "/performance/trace/b6e75da452bf40ee8330af41c5989545/"
94+
}
95+
}
96+
}
97+
}
98+
```
99+
100+
### performanceSpan
101+
102+
Similar to breadcrumbs, `"performanceSpan"` has a similar interface to Spans. The following is an example of a network request made in the browser. We have additional instrumentation to capture request and response payloads when configured to do so.
103+
104+
```json
105+
{
106+
"type": 5,
107+
"timestamp": 1710854008431,
108+
"data": {
109+
"tag": "performanceSpan",
110+
"payload": {
111+
"op": "resource.fetch",
112+
"description": "https://us.sentry.io/api/0/projects/foo/javascript/events/eea92bc02315448591e159d8138ef3e8/owners/",
113+
"startTimestamp": 1710854008.431,
114+
"endTimestamp": 1710854009.234,
115+
"data": {
116+
"method": "GET",
117+
"statusCode": 200,
118+
"request": {
119+
"headers": {
120+
"content-type": "application/json",
121+
"accept": "application/json; charset=utf-8",
122+
"sentry-trace": "b07d0e356aa1477bb279d9fe5680fcd0-83881f299ca64b4f-1"
123+
}
124+
},
125+
"response": {
126+
"headers": {
127+
"content-length": "36",
128+
"content-type": "application/json"
129+
},
130+
"size": 36,
131+
"body": {
132+
"owners": [],
133+
"rule": null,
134+
"rules": []
135+
}
136+
}
137+
}
138+
}
139+
}
140+
},
141+
142+
```
143+
144+
## Mobile Replay Events
145+
146+
Mobile replays are captured as video rather than a series of mutations. In order to support mobile replays, the following custom event is required:
147+
148+
| property | type | description |
149+
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
150+
| type | `5` | Custom event |
151+
| data.tag | `"video"` | The string `"video"` |
152+
| data.payload.duration | integer | The video duration in milliseconds |
153+
| data.payload.segmentId | integer | The segment id. This should be the same as the replay segment id. This will be used by the UI to fetch the video from the Sentry API |
154+
155+
```json
156+
{
157+
"type": 5,
158+
"timestamp": 1710854008431,
159+
"data": {
160+
"tag": "video",
161+
"payload": {
162+
"duration": 5000,
163+
"segmentId": 0
164+
}
165+
}
166+
}
167+
```
168+
169+
### Additional Events
170+
171+
Mobile replays follow the same rrweb protocol, but because mobile replays are captured by video, a majority of the rrweb events do not apply. Outlined below are the ones that do.
172+
173+
#### Meta Event
174+
175+
This should be emitted at the start of a replay (i.e. on the first segment) and when the user's viewport dimensions change.
176+
177+
| property | type | description |
178+
| ----------- | ------- | ---------------------------------- |
179+
| type | `4` | "Meta" event |
180+
| data.href | string | The current URI |
181+
| data.width | integer | The width of the current viewport |
182+
| data.height | integer | The height of the current viewport |
183+
184+
```json
185+
{
186+
"type": 4,
187+
"timestamp": 1710854008431,
188+
"data": {
189+
"href": "file://screen",
190+
"width": 360,
191+
"height": 800
192+
}
193+
}
194+
```
195+
196+
#### Touch Interactions
197+
198+
| property | type | description |
199+
| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
200+
| type | `3` | "Incremental mutation" event |
201+
| data.source | `2` | "Mouse Interaction" |
202+
| data.type | integer | [MouseInteraction](https://github.com/getsentry/rrweb/blob/0722035e75a9aeedd716107cbcc949eba6da2a6a/packages/types/src/index.ts#L361-L373) enum. TouchStart = 7, TouchMove_Departed = 8, TouchEnd = 9, TouchCancel = 10 |
203+
| data.id | integer | Unique id of the event |
204+
| data.x | integer | The x-coordinate of the touch event |
205+
| data.y | integer | The y-coordinate of the touch event |
206+
| data.pointerType | `2` | [PointerTypes](https://github.com/getsentry/rrweb/blob/0722035e75a9aeedd716107cbcc949eba6da2a6a/packages/types/src/index.ts#L375-L379) enum. Touch = 2 |

0 commit comments

Comments
 (0)