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                && let Some(k) = o_k.as_str()
238                && k.eq_ignore_ascii_case("user-agent")
239            {
240                return v.as_str();
241            }
242        }
243
244        None
245    }
246}
247
248impl Getter for Replay {
249    fn get_value(&self, path: &str) -> Option<Val<'_>> {
250        Some(match path.strip_prefix("event.")? {
251            // Simple fields
252            "release" => self.release.as_str()?.into(),
253            "dist" => self.dist.as_str()?.into(),
254            "environment" => self.environment.as_str()?.into(),
255            "platform" => self.platform.as_str().unwrap_or("other").into(),
256
257            // Fields in top level structures (called "interfaces" in Sentry)
258            "user.email" => or_none(&self.user.value()?.email)?.into(),
259            "user.id" => or_none(&self.user.value()?.id)?.into(),
260            "user.ip_address" => self.user.value()?.ip_address.as_str()?.into(),
261            "user.name" => self.user.value()?.name.as_str()?.into(),
262            "user.segment" => or_none(&self.user.value()?.segment)?.into(),
263            "user.geo.city" => self.user.value()?.geo.value()?.city.as_str()?.into(),
264            "user.geo.country_code" => self
265                .user
266                .value()?
267                .geo
268                .value()?
269                .country_code
270                .as_str()?
271                .into(),
272            "user.geo.region" => self.user.value()?.geo.value()?.region.as_str()?.into(),
273            "user.geo.subdivision" => self.user.value()?.geo.value()?.subdivision.as_str()?.into(),
274            "request.method" => self.request.value()?.method.as_str()?.into(),
275            "request.url" => self.request.value()?.url.as_str()?.into(),
276            "sdk.name" => self.sdk.value()?.name.as_str()?.into(),
277            "sdk.version" => self.sdk.value()?.version.as_str()?.into(),
278
279            // Computed fields (after normalization).
280            "sentry_user" => self.user.value()?.sentry_user.as_str()?.into(),
281
282            // Partial implementation of contexts.
283            "contexts.app.in_foreground" => {
284                self.context::<AppContext>()?.in_foreground.value()?.into()
285            }
286            "contexts.device.arch" => self.context::<DeviceContext>()?.arch.as_str()?.into(),
287            "contexts.device.battery_level" => self
288                .context::<DeviceContext>()?
289                .battery_level
290                .value()?
291                .into(),
292            "contexts.device.brand" => self.context::<DeviceContext>()?.brand.as_str()?.into(),
293            "contexts.device.charging" => self.context::<DeviceContext>()?.charging.value()?.into(),
294            "contexts.device.family" => self.context::<DeviceContext>()?.family.as_str()?.into(),
295            "contexts.device.model" => self.context::<DeviceContext>()?.model.as_str()?.into(),
296            "contexts.device.locale" => self.context::<DeviceContext>()?.locale.as_str()?.into(),
297            "contexts.device.online" => self.context::<DeviceContext>()?.online.value()?.into(),
298            "contexts.device.orientation" => self
299                .context::<DeviceContext>()?
300                .orientation
301                .as_str()?
302                .into(),
303            "contexts.device.name" => self.context::<DeviceContext>()?.name.as_str()?.into(),
304            "contexts.device.screen_density" => self
305                .context::<DeviceContext>()?
306                .screen_density
307                .value()?
308                .into(),
309            "contexts.device.screen_dpi" => {
310                self.context::<DeviceContext>()?.screen_dpi.value()?.into()
311            }
312            "contexts.device.screen_width_pixels" => self
313                .context::<DeviceContext>()?
314                .screen_width_pixels
315                .value()?
316                .into(),
317            "contexts.device.screen_height_pixels" => self
318                .context::<DeviceContext>()?
319                .screen_height_pixels
320                .value()?
321                .into(),
322            "contexts.device.simulator" => {
323                self.context::<DeviceContext>()?.simulator.value()?.into()
324            }
325            "contexts.os.build" => self.context::<OsContext>()?.build.as_str()?.into(),
326            "contexts.os.kernel_version" => {
327                self.context::<OsContext>()?.kernel_version.as_str()?.into()
328            }
329            "contexts.os.name" => self.context::<OsContext>()?.name.as_str()?.into(),
330            "contexts.os.version" => self.context::<OsContext>()?.version.as_str()?.into(),
331            "contexts.browser.name" => self.context::<BrowserContext>()?.name.as_str()?.into(),
332            "contexts.browser.version" => {
333                self.context::<BrowserContext>()?.version.as_str()?.into()
334            }
335            "contexts.profile.profile_id" => {
336                (&self.context::<ProfileContext>()?.profile_id.value()?.0).into()
337            }
338            "contexts.device.uuid" => self.context::<DeviceContext>()?.uuid.value()?.into(),
339            "contexts.trace.status" => self
340                .context::<TraceContext>()?
341                .status
342                .value()?
343                .as_str()
344                .into(),
345            "contexts.trace.op" => self.context::<TraceContext>()?.op.as_str()?.into(),
346            "contexts.response.status_code" => self
347                .context::<ResponseContext>()?
348                .status_code
349                .value()?
350                .into(),
351            "contexts.unreal.crash_type" => match self.contexts.value()?.get_key("unreal")? {
352                super::Context::Other(context) => context.get("crash_type")?.value()?.into(),
353                _ => return None,
354            },
355            "contexts.ota_updates.channel" => self
356                .context::<OTAUpdatesContext>()?
357                .channel
358                .as_str()?
359                .into(),
360            "contexts.ota_updates.runtime_version" => self
361                .context::<OTAUpdatesContext>()?
362                .runtime_version
363                .as_str()?
364                .into(),
365            "contexts.ota_updates.update_id" => self
366                .context::<OTAUpdatesContext>()?
367                .update_id
368                .as_str()?
369                .into(),
370
371            // Dynamic access to certain data bags
372            path => {
373                if let Some(rest) = path.strip_prefix("tags.") {
374                    self.tags.value()?.get(rest)?.into()
375                } else {
376                    let rest = path.strip_prefix("request.headers.")?;
377                    self.request
378                        .value()?
379                        .headers
380                        .value()?
381                        .get_header(rest)?
382                        .into()
383                }
384            }
385        })
386    }
387}
388
389fn or_none(string: &Annotated<impl AsRef<str>>) -> Option<&str> {
390    match string.as_str() {
391        None | Some("") => None,
392        Some(other) => Some(other),
393    }
394}
395
396#[cfg(test)]
397mod tests {
398    use chrono::{TimeZone, Utc};
399
400    use crate::protocol::TagEntry;
401
402    use super::*;
403
404    #[test]
405    fn test_event_roundtrip() {
406        // NOTE: Interfaces will be tested separately.
407        let json = r#"{
408  "event_id": "52df9022835246eeb317dbd739ccd059",
409  "replay_id": "52df9022835246eeb317dbd739ccd059",
410  "segment_id": 0,
411  "replay_type": "session",
412  "error_sample_rate": 0.5,
413  "session_sample_rate": 0.5,
414  "timestamp": 946684800.0,
415  "replay_start_timestamp": 946684800.0,
416  "urls": ["localhost:9000"],
417  "error_ids": ["52df9022835246eeb317dbd739ccd059"],
418  "trace_ids": ["52df9022835246eeb317dbd739ccd059"],
419  "platform": "myplatform",
420  "release": "myrelease",
421  "dist": "mydist",
422  "environment": "myenv",
423  "tags": [
424    [
425      "tag",
426      "value"
427    ]
428  ]
429}"#;
430
431        let replay = Annotated::new(Replay {
432            event_id: Annotated::new(EventId("52df9022835246eeb317dbd739ccd059".parse().unwrap())),
433            replay_id: Annotated::new(EventId("52df9022835246eeb317dbd739ccd059".parse().unwrap())),
434            replay_type: Annotated::new("session".to_owned()),
435            segment_id: Annotated::new(0),
436            timestamp: Annotated::new(Utc.with_ymd_and_hms(2000, 1, 1, 0, 0, 0).unwrap().into()),
437            replay_start_timestamp: Annotated::new(
438                Utc.with_ymd_and_hms(2000, 1, 1, 0, 0, 0).unwrap().into(),
439            ),
440            urls: Annotated::new(vec![Annotated::new("localhost:9000".to_owned())]),
441            error_ids: Annotated::new(vec![Annotated::new(
442                Uuid::parse_str("52df9022835246eeb317dbd739ccd059").unwrap(),
443            )]),
444            trace_ids: Annotated::new(vec![Annotated::new(
445                Uuid::parse_str("52df9022835246eeb317dbd739ccd059").unwrap(),
446            )]),
447            platform: Annotated::new("myplatform".to_owned()),
448            release: Annotated::new("myrelease".to_owned().into()),
449            dist: Annotated::new("mydist".to_owned()),
450            environment: Annotated::new("myenv".to_owned()),
451            tags: {
452                let items = vec![Annotated::new(TagEntry(
453                    Annotated::new("tag".to_owned()),
454                    Annotated::new("value".to_owned()),
455                ))];
456                Annotated::new(Tags(items.into()))
457            },
458            ..Default::default()
459        });
460
461        assert_eq!(replay, Annotated::from_json(json).unwrap());
462    }
463
464    #[test]
465    fn test_lenient_release() {
466        let input = r#"{"release":42}"#;
467        let output = r#"{"release":"42"}"#;
468        let event = Annotated::new(Replay {
469            release: Annotated::new("42".to_owned().into()),
470            ..Default::default()
471        });
472
473        assert_eq!(event, Annotated::from_json(input).unwrap());
474        assert_eq!(output, event.to_json().unwrap());
475    }
476
477    #[test]
478    fn test_ota_updates_context_getter() {
479        let mut contexts = Contexts::new();
480        contexts.add(OTAUpdatesContext {
481            channel: Annotated::new("production".to_owned()),
482            runtime_version: Annotated::new("1.0.0".to_owned()),
483            update_id: Annotated::new("12345678-1234-1234-1234-1234567890ab".to_owned()),
484            ..OTAUpdatesContext::default()
485        });
486
487        let replay = Replay {
488            contexts: Annotated::new(contexts),
489            ..Default::default()
490        };
491
492        assert_eq!(
493            Some(Val::String("production")),
494            replay.get_value("event.contexts.ota_updates.channel")
495        );
496        assert_eq!(
497            Some(Val::String("1.0.0")),
498            replay.get_value("event.contexts.ota_updates.runtime_version")
499        );
500        assert_eq!(
501            Some(Val::String("12345678-1234-1234-1234-1234567890ab")),
502            replay.get_value("event.contexts.ota_updates.update_id")
503        );
504    }
505}
relay_event_schema/protocol/replay.rs

relay_event_schema/protocol/
replay.rs
