relay_event_schema/protocol/
replay.rs

1//! Replay processing and normalization module.
2//!
3//! Replays are multi-part values sent from Sentry integrations spanning arbitrary time-periods.
4//! They are ingested incrementally.
5//!
6//! # Protocol
7//!
8//! Relay is expecting a JSON object with some mandatory metadata.  However, environment and user
9//! metadata is usually sent in addition to the minimal payload.
10//!
11//! ```json
12//! {
13//!     "type": "replay_event",
14//!     "replay_id": "d2132d31b39445f1938d7e21b6bf0ec4",
15//!     "event_id": "63c5b0f895441a94340183c5f1e74cd4",
16//!     "segment_id": 0,
17//!     "timestamp": 1597976392.6542819,
18//!     "replay_start_timestamp": 1597976392.6542819,
19//!     "urls": ["https://sentry.io"],
20//!     "error_ids": ["d2132d31b39445f1938d7e21b6bf0ec4"],
21//!     "trace_ids": ["63c5b0f895441a94340183c5f1e74cd4"],
22//!     "request": {
23//!         "headers": {"User-Agent": "Mozilla/5.0..."}
24//!     },
25//! }
26//! ```
27
28use relay_protocol::{Annotated, Array, Empty, FromValue, Getter, IntoValue, Val};
29
30use crate::processor::ProcessValue;
31use crate::protocol::{
32    AppContext, BrowserContext, ClientSdkInfo, Contexts, DefaultContext, DeviceContext, EventId,
33    LenientString, OTAUpdatesContext, OsContext, ProfileContext, Request, ResponseContext, Tags,
34    Timestamp, TraceContext, User,
35};
36use uuid::Uuid;
37
38#[derive(Clone, Debug, Default, PartialEq, Empty, FromValue, IntoValue, ProcessValue)]
39#[metastructure(process_func = "process_replay", value_type = "Replay")]
40pub struct Replay {
41    /// Unique identifier of this event.
42    ///
43    /// Hexadecimal string representing a uuid4 value. The length is exactly 32 characters. Dashes
44    /// are not allowed. Has to be lowercase.
45    ///
46    /// Even though this field is backfilled on the server with a new uuid4, it is strongly
47    /// recommended to generate that uuid4 clientside. There are some features like user feedback
48    /// which are easier to implement that way, and debugging in case events get lost in your
49    /// Sentry installation is also easier.
50    ///
51    /// Example:
52    ///
53    /// ```json
54    /// {
55    ///   "event_id": "fc6d8c0c43fc4630ad850ee518f1b9d0"
56    /// }
57    /// ```
58    pub event_id: Annotated<EventId>,
59
60    /// Replay identifier.
61    ///
62    /// Hexadecimal string representing a uuid4 value. The length is exactly 32 characters. Dashes
63    /// are not allowed. Has to be lowercase.
64    ///
65    /// Example:
66    ///
67    /// ```json
68    /// {
69    ///   "replay_id": "fc6d8c0c43fc4630ad850ee518f1b9d0"
70    /// }
71    /// ```
72    pub replay_id: Annotated<EventId>,
73
74    /// The type of sampling that captured the replay.
75    ///
76    /// A string enumeration.  One of "session" or "error".
77    ///
78    /// Example:
79    ///
80    /// ```json
81    /// {
82    ///   "replay_type": "session"
83    /// }
84    /// ```
85    #[metastructure(max_chars = 64)]
86    pub replay_type: Annotated<String>,
87
88    /// Segment identifier.
89    ///
90    /// A number representing a unique segment identifier in the chain of replay segments.
91    /// Segment identifiers are temporally ordered but can be received by the Relay service in any
92    /// order.
93    ///
94    /// Example:
95    ///
96    /// ```json
97    /// {
98    ///   "segment_id": 10
99    /// }
100    /// ```
101    pub segment_id: Annotated<u64>,
102
103    /// Timestamp when the event was created.
104    ///
105    /// Indicates when the segment was created in the Sentry SDK. The format is either a string as
106    /// defined in [RFC 3339](https://tools.ietf.org/html/rfc3339) or a numeric (integer or float)
107    /// value representing the number of seconds that have elapsed since the [Unix
108    /// epoch](https://en.wikipedia.org/wiki/Unix_time).
109    ///
110    /// Timezone is assumed to be UTC if missing.
111    ///
112    /// Sub-microsecond precision is not preserved with numeric values due to precision
113    /// limitations with floats (at least in our systems). With that caveat in mind, just send
114    /// whatever is easiest to produce.
115    ///
116    /// All timestamps in the event protocol are formatted this way.
117    ///
118    /// # Example
119    ///
120    /// All of these are the same date:
121    ///
122    /// ```json
123    /// { "timestamp": "2011-05-02T17:41:36Z" }
124    /// { "timestamp": "2011-05-02T17:41:36" }
125    /// { "timestamp": "2011-05-02T17:41:36.000" }
126    /// { "timestamp": 1304358096.0 }
127    /// ```
128    pub timestamp: Annotated<Timestamp>,
129
130    /// Timestamp when the replay was created.  Typically only specified on the initial segment.
131    pub replay_start_timestamp: Annotated<Timestamp>,
132
133    /// A list of URLs visted during the lifetime of the segment.
134    #[metastructure(pii = "true", max_depth = 7, max_bytes = 8192)]
135    pub urls: Annotated<Array<String>>,
136
137    /// A list of error-ids discovered during the lifetime of the segment.
138    #[metastructure(max_depth = 5, max_bytes = 2048)]
139    pub error_ids: Annotated<Array<Uuid>>,
140
141    /// A list of trace-ids discovered during the lifetime of the segment.
142    #[metastructure(max_depth = 5, max_bytes = 2048)]
143    pub trace_ids: Annotated<Array<Uuid>>,
144
145    /// Contexts describing the environment (e.g. device, os or browser).
146    #[metastructure(skip_serialization = "empty")]
147    pub contexts: Annotated<Contexts>,
148
149    /// Platform identifier of this event (defaults to "other").
150    ///
151    /// A string representing the platform the SDK is submitting from. This will be used by the
152    /// Sentry interface to customize various components in the interface.
153    #[metastructure(max_chars = 64)]
154    pub platform: Annotated<String>,
155
156    /// The release version of the application.
157    ///
158    /// **Release versions must be unique across all projects in your organization.** This value
159    /// can be the git SHA for the given project, or a product identifier with a semantic version.
160    #[metastructure(
161        max_chars = 200,
162        required = false,
163        trim_whitespace = true,
164        nonempty = true,
165        skip_serialization = "empty"
166    )]
167    pub release: Annotated<LenientString>,
168
169    /// Program's distribution identifier.
170    ///
171    /// The distribution of the application.
172    ///
173    /// Distributions are used to disambiguate build or deployment variants of the same release of
174    /// an application. For example, the dist can be the build number of an XCode build or the
175    /// version code of an Android build.
176    #[metastructure(
177        allow_chars = "a-zA-Z0-9_.-",
178        trim_whitespace = true,
179        required = false,
180        nonempty = true,
181        max_chars = 64
182    )]
183    pub dist: Annotated<String>,
184
185    /// The environment name, such as `production` or `staging`.
186    ///
187    /// ```json
188    /// { "environment": "production" }
189    /// ```
190    #[metastructure(
191        max_chars = 64,
192        nonempty = true,
193        required = false,
194        trim_whitespace = true
195    )]
196    pub environment: Annotated<String>,
197
198    /// Custom tags for this event.
199    ///
200    /// A map or list of tags for this event. Each tag must be less than 200 characters.
201    #[metastructure(skip_serialization = "empty", pii = "true")]
202    pub tags: Annotated<Tags>,
203
204    /// Static value. Should always be "replay_event".
205    #[metastructure(field = "type", max_chars = 64)]
206    pub ty: Annotated<String>,
207
208    /// Information about the user who triggered this event.
209    #[metastructure(skip_serialization = "empty")]
210    pub user: Annotated<User>,
211
212    /// Information about a web request that occurred during the event.
213    #[metastructure(skip_serialization = "empty")]
214    pub request: Annotated<Request>,
215
216    /// Information about the Sentry SDK that generated this event.
217    #[metastructure(field = "sdk")]
218    #[metastructure(skip_serialization = "empty")]
219    pub sdk: Annotated<ClientSdkInfo>,
220}
221
222impl Replay {
223    /// Returns a reference to the context if it exists in its default key.
224    pub fn context<C: DefaultContext>(&self) -> Option<&C> {
225        self.contexts.value()?.get()
226    }
227
228    /// Returns the raw user agent string.
229    ///
230    /// Returns `Some` if the event's request interface contains a `user-agent` header. Returns
231    /// `None` otherwise.
232    pub fn user_agent(&self) -> Option<&str> {
233        let headers = self.request.value()?.headers.value()?;
234
235        for item in headers.iter() {
236            if let Some((o_k, v)) = item.value() {
237                if let Some(k) = o_k.as_str() {
238                    if k.eq_ignore_ascii_case("user-agent") {
239                        return v.as_str();
240                    }
241                }
242            }
243        }
244
245        None
246    }
247}
248
249impl Getter for Replay {
250    fn get_value(&self, path: &str) -> Option<Val<'_>> {
251        Some(match path.strip_prefix("event.")? {
252            // Simple fields
253            "release" => self.release.as_str()?.into(),
254            "dist" => self.dist.as_str()?.into(),
255            "environment" => self.environment.as_str()?.into(),
256            "platform" => self.platform.as_str().unwrap_or("other").into(),
257
258            // Fields in top level structures (called "interfaces" in Sentry)
259            "user.email" => or_none(&self.user.value()?.email)?.into(),
260            "user.id" => or_none(&self.user.value()?.id)?.into(),
261            "user.ip_address" => self.user.value()?.ip_address.as_str()?.into(),
262            "user.name" => self.user.value()?.name.as_str()?.into(),
263            "user.segment" => or_none(&self.user.value()?.segment)?.into(),
264            "user.geo.city" => self.user.value()?.geo.value()?.city.as_str()?.into(),
265            "user.geo.country_code" => self
266                .user
267                .value()?
268                .geo
269                .value()?
270                .country_code
271                .as_str()?
272                .into(),
273            "user.geo.region" => self.user.value()?.geo.value()?.region.as_str()?.into(),
274            "user.geo.subdivision" => self.user.value()?.geo.value()?.subdivision.as_str()?.into(),
275            "request.method" => self.request.value()?.method.as_str()?.into(),
276            "request.url" => self.request.value()?.url.as_str()?.into(),
277            "sdk.name" => self.sdk.value()?.name.as_str()?.into(),
278            "sdk.version" => self.sdk.value()?.version.as_str()?.into(),
279
280            // Computed fields (after normalization).
281            "sentry_user" => self.user.value()?.sentry_user.as_str()?.into(),
282
283            // Partial implementation of contexts.
284            "contexts.app.in_foreground" => {
285                self.context::<AppContext>()?.in_foreground.value()?.into()
286            }
287            "contexts.device.arch" => self.context::<DeviceContext>()?.arch.as_str()?.into(),
288            "contexts.device.battery_level" => self
289                .context::<DeviceContext>()?
290                .battery_level
291                .value()?
292                .into(),
293            "contexts.device.brand" => self.context::<DeviceContext>()?.brand.as_str()?.into(),
294            "contexts.device.charging" => self.context::<DeviceContext>()?.charging.value()?.into(),
295            "contexts.device.family" => self.context::<DeviceContext>()?.family.as_str()?.into(),
296            "contexts.device.model" => self.context::<DeviceContext>()?.model.as_str()?.into(),
297            "contexts.device.locale" => self.context::<DeviceContext>()?.locale.as_str()?.into(),
298            "contexts.device.online" => self.context::<DeviceContext>()?.online.value()?.into(),
299            "contexts.device.orientation" => self
300                .context::<DeviceContext>()?
301                .orientation
302                .as_str()?
303                .into(),
304            "contexts.device.name" => self.context::<DeviceContext>()?.name.as_str()?.into(),
305            "contexts.device.screen_density" => self
306                .context::<DeviceContext>()?
307                .screen_density
308                .value()?
309                .into(),
310            "contexts.device.screen_dpi" => {
311                self.context::<DeviceContext>()?.screen_dpi.value()?.into()
312            }
313            "contexts.device.screen_width_pixels" => self
314                .context::<DeviceContext>()?
315                .screen_width_pixels
316                .value()?
317                .into(),
318            "contexts.device.screen_height_pixels" => self
319                .context::<DeviceContext>()?
320                .screen_height_pixels
321                .value()?
322                .into(),
323            "contexts.device.simulator" => {
324                self.context::<DeviceContext>()?.simulator.value()?.into()
325            }
326            "contexts.os.build" => self.context::<OsContext>()?.build.as_str()?.into(),
327            "contexts.os.kernel_version" => {
328                self.context::<OsContext>()?.kernel_version.as_str()?.into()
329            }
330            "contexts.os.name" => self.context::<OsContext>()?.name.as_str()?.into(),
331            "contexts.os.version" => self.context::<OsContext>()?.version.as_str()?.into(),
332            "contexts.browser.name" => self.context::<BrowserContext>()?.name.as_str()?.into(),
333            "contexts.browser.version" => {
334                self.context::<BrowserContext>()?.version.as_str()?.into()
335            }
336            "contexts.profile.profile_id" => {
337                (&self.context::<ProfileContext>()?.profile_id.value()?.0).into()
338            }
339            "contexts.device.uuid" => self.context::<DeviceContext>()?.uuid.value()?.into(),
340            "contexts.trace.status" => self
341                .context::<TraceContext>()?
342                .status
343                .value()?
344                .as_str()
345                .into(),
346            "contexts.trace.op" => self.context::<TraceContext>()?.op.as_str()?.into(),
347            "contexts.response.status_code" => self
348                .context::<ResponseContext>()?
349                .status_code
350                .value()?
351                .into(),
352            "contexts.unreal.crash_type" => match self.contexts.value()?.get_key("unreal")? {
353                super::Context::Other(context) => context.get("crash_type")?.value()?.into(),
354                _ => return None,
355            },
356            "contexts.ota_updates.channel" => self
357                .context::<OTAUpdatesContext>()?
358                .channel
359                .as_str()?
360                .into(),
361            "contexts.ota_updates.runtime_version" => self
362                .context::<OTAUpdatesContext>()?
363                .runtime_version
364                .as_str()?
365                .into(),
366            "contexts.ota_updates.update_id" => self
367                .context::<OTAUpdatesContext>()?
368                .update_id
369                .as_str()?
370                .into(),
371
372            // Dynamic access to certain data bags
373            path => {
374                if let Some(rest) = path.strip_prefix("tags.") {
375                    self.tags.value()?.get(rest)?.into()
376                } else if let Some(rest) = path.strip_prefix("request.headers.") {
377                    self.request
378                        .value()?
379                        .headers
380                        .value()?
381                        .get_header(rest)?
382                        .into()
383                } else {
384                    return None;
385                }
386            }
387        })
388    }
389}
390
391fn or_none(string: &Annotated<impl AsRef<str>>) -> Option<&str> {
392    match string.as_str() {
393        None | Some("") => None,
394        Some(other) => Some(other),
395    }
396}
397
398#[cfg(test)]
399mod tests {
400    use chrono::{TimeZone, Utc};
401
402    use crate::protocol::TagEntry;
403
404    use super::*;
405
406    #[test]
407    fn test_event_roundtrip() {
408        // NOTE: Interfaces will be tested separately.
409        let json = r#"{
410  "event_id": "52df9022835246eeb317dbd739ccd059",
411  "replay_id": "52df9022835246eeb317dbd739ccd059",
412  "segment_id": 0,
413  "replay_type": "session",
414  "error_sample_rate": 0.5,
415  "session_sample_rate": 0.5,
416  "timestamp": 946684800.0,
417  "replay_start_timestamp": 946684800.0,
418  "urls": ["localhost:9000"],
419  "error_ids": ["52df9022835246eeb317dbd739ccd059"],
420  "trace_ids": ["52df9022835246eeb317dbd739ccd059"],
421  "platform": "myplatform",
422  "release": "myrelease",
423  "dist": "mydist",
424  "environment": "myenv",
425  "tags": [
426    [
427      "tag",
428      "value"
429    ]
430  ]
431}"#;
432
433        let replay = Annotated::new(Replay {
434            event_id: Annotated::new(EventId("52df9022835246eeb317dbd739ccd059".parse().unwrap())),
435            replay_id: Annotated::new(EventId("52df9022835246eeb317dbd739ccd059".parse().unwrap())),
436            replay_type: Annotated::new("session".to_string()),
437            segment_id: Annotated::new(0),
438            timestamp: Annotated::new(Utc.with_ymd_and_hms(2000, 1, 1, 0, 0, 0).unwrap().into()),
439            replay_start_timestamp: Annotated::new(
440                Utc.with_ymd_and_hms(2000, 1, 1, 0, 0, 0).unwrap().into(),
441            ),
442            urls: Annotated::new(vec![Annotated::new("localhost:9000".to_string())]),
443            error_ids: Annotated::new(vec![Annotated::new(
444                Uuid::parse_str("52df9022835246eeb317dbd739ccd059").unwrap(),
445            )]),
446            trace_ids: Annotated::new(vec![Annotated::new(
447                Uuid::parse_str("52df9022835246eeb317dbd739ccd059").unwrap(),
448            )]),
449            platform: Annotated::new("myplatform".to_string()),
450            release: Annotated::new("myrelease".to_string().into()),
451            dist: Annotated::new("mydist".to_string()),
452            environment: Annotated::new("myenv".to_string()),
453            tags: {
454                let items = vec![Annotated::new(TagEntry(
455                    Annotated::new("tag".to_string()),
456                    Annotated::new("value".to_string()),
457                ))];
458                Annotated::new(Tags(items.into()))
459            },
460            ..Default::default()
461        });
462
463        assert_eq!(replay, Annotated::from_json(json).unwrap());
464    }
465
466    #[test]
467    fn test_lenient_release() {
468        let input = r#"{"release":42}"#;
469        let output = r#"{"release":"42"}"#;
470        let event = Annotated::new(Replay {
471            release: Annotated::new("42".to_string().into()),
472            ..Default::default()
473        });
474
475        assert_eq!(event, Annotated::from_json(input).unwrap());
476        assert_eq!(output, event.to_json().unwrap());
477    }
478
479    #[test]
480    fn test_ota_updates_context_getter() {
481        let mut contexts = Contexts::new();
482        contexts.add(OTAUpdatesContext {
483            channel: Annotated::new("production".to_string()),
484            runtime_version: Annotated::new("1.0.0".to_string()),
485            update_id: Annotated::new("12345678-1234-1234-1234-1234567890ab".to_string()),
486            ..OTAUpdatesContext::default()
487        });
488
489        let replay = Replay {
490            contexts: Annotated::new(contexts),
491            ..Default::default()
492        };
493
494        assert_eq!(
495            Some(Val::String("production")),
496            replay.get_value("event.contexts.ota_updates.channel")
497        );
498        assert_eq!(
499            Some(Val::String("1.0.0")),
500            replay.get_value("event.contexts.ota_updates.runtime_version")
501        );
502        assert_eq!(
503            Some(Val::String("12345678-1234-1234-1234-1234567890ab")),
504            replay.get_value("event.contexts.ota_updates.update_id")
505        );
506    }
507}
relay_event_schema/protocol/replay.rs

relay_event_schema/protocol/
replay.rs
