sentry_types/protocol/
v7.rs

1//! The current latest sentry protocol version.
2//!
3//! Most constructs in the protocol map directly to types here but some
4//! cleanup by renaming attributes has been applied.  The idea here is that
5//! a future sentry protocol will be a cleanup of the old one and is mapped
6//! to similar values on the rust side.
7
8use std::borrow::Cow;
9use std::cmp;
10use std::convert::TryFrom;
11use std::fmt;
12use std::iter::FromIterator;
13use std::net::{AddrParseError, IpAddr};
14use std::ops;
15use std::str;
16use std::time::SystemTime;
17
18use self::debugid::{CodeId, DebugId};
19use serde::{de, Deserialize, Deserializer, Serialize, Serializer};
20use thiserror::Error;
21
22pub use url::Url;
23pub use uuid::Uuid;
24
25use crate::utils::{ts_rfc3339_opt, ts_seconds_float};
26
27pub use super::attachment::*;
28pub use super::envelope::*;
29pub use super::monitor::*;
30pub use super::session::*;
31
32/// An arbitrary (JSON) value.
33pub mod value {
34    pub use serde_json::value::{from_value, to_value, Index, Map, Number, Value};
35}
36
37/// The internally used arbitrary data map type.
38pub mod map {
39    pub use std::collections::btree_map::{BTreeMap as Map, *};
40}
41
42/// Represents a debug ID.
43pub mod debugid {
44    pub use debugid::{BreakpadFormat, CodeId, DebugId, ParseDebugIdError};
45}
46
47/// An arbitrary (JSON) value.
48pub use self::value::Value;
49
50/// The internally used map type.
51pub use self::map::Map;
52
53/// A wrapper type for collections with attached meta data.
54///
55/// The JSON payload can either directly be an array or an object containing a `values` field and
56/// arbitrary other fields. All other fields will be collected into `Values::data` when
57/// deserializing and re-serialized in the same place. The shorthand array notation is always
58/// reserialized as object.
59#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
60pub struct Values<T> {
61    /// The values of the collection.
62    pub values: Vec<T>,
63}
64
65impl<T> Values<T> {
66    /// Creates an empty values struct.
67    pub fn new() -> Values<T> {
68        Values { values: Vec::new() }
69    }
70
71    /// Checks whether this struct is empty in both values and data.
72    pub fn is_empty(&self) -> bool {
73        self.values.is_empty()
74    }
75}
76
77impl<T> Default for Values<T> {
78    fn default() -> Self {
79        // Default implemented manually even if <T> does not impl Default.
80        Values::new()
81    }
82}
83
84impl<T> From<Vec<T>> for Values<T> {
85    fn from(values: Vec<T>) -> Self {
86        Values { values }
87    }
88}
89
90impl<T> AsRef<[T]> for Values<T> {
91    fn as_ref(&self) -> &[T] {
92        &self.values
93    }
94}
95
96impl<T> AsMut<Vec<T>> for Values<T> {
97    fn as_mut(&mut self) -> &mut Vec<T> {
98        &mut self.values
99    }
100}
101
102impl<T> ops::Deref for Values<T> {
103    type Target = [T];
104
105    fn deref(&self) -> &Self::Target {
106        &self.values
107    }
108}
109
110impl<T> ops::DerefMut for Values<T> {
111    fn deref_mut(&mut self) -> &mut Self::Target {
112        &mut self.values
113    }
114}
115
116impl<T> FromIterator<T> for Values<T> {
117    fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self {
118        Vec::<T>::from_iter(iter).into()
119    }
120}
121
122impl<T> Extend<T> for Values<T> {
123    fn extend<I>(&mut self, iter: I)
124    where
125        I: IntoIterator<Item = T>,
126    {
127        self.values.extend(iter)
128    }
129}
130
131impl<'a, T> IntoIterator for &'a mut Values<T> {
132    type Item = <&'a mut Vec<T> as IntoIterator>::Item;
133    type IntoIter = <&'a mut Vec<T> as IntoIterator>::IntoIter;
134
135    fn into_iter(self) -> Self::IntoIter {
136        self.values.iter_mut()
137    }
138}
139
140impl<'a, T> IntoIterator for &'a Values<T> {
141    type Item = <&'a Vec<T> as IntoIterator>::Item;
142    type IntoIter = <&'a Vec<T> as IntoIterator>::IntoIter;
143
144    fn into_iter(self) -> Self::IntoIter {
145        self.values.iter()
146    }
147}
148
149impl<T> IntoIterator for Values<T> {
150    type Item = <Vec<T> as IntoIterator>::Item;
151    type IntoIter = <Vec<T> as IntoIterator>::IntoIter;
152
153    fn into_iter(self) -> Self::IntoIter {
154        self.values.into_iter()
155    }
156}
157
158/// Represents a log entry message.
159///
160/// A log message is similar to the `message` attribute on the event itself but
161/// can additionally hold optional parameters.
162#[derive(Serialize, Deserialize, Default, Clone, Debug, PartialEq)]
163pub struct LogEntry {
164    /// The log message with parameters replaced by `%s`
165    pub message: String,
166    /// Positional parameters to be inserted into the log entry.
167    #[serde(default, skip_serializing_if = "Vec::is_empty")]
168    pub params: Vec<Value>,
169}
170
171/// Represents a frame.
172#[derive(Serialize, Deserialize, Default, Clone, Debug, PartialEq)]
173pub struct Frame {
174    /// The name of the function is known.
175    ///
176    /// Note that this might include the name of a class as well if that makes
177    /// sense for the language.
178    #[serde(default, skip_serializing_if = "Option::is_none")]
179    pub function: Option<String>,
180    /// The potentially mangled name of the symbol as it appears in an executable.
181    ///
182    /// This is different from a function name by generally being the mangled
183    /// name that appears natively in the binary.  This is relevant for languages
184    /// like Swift, C++ or Rust.
185    #[serde(default, skip_serializing_if = "Option::is_none")]
186    pub symbol: Option<String>,
187    /// The name of the module the frame is contained in.
188    ///
189    /// Note that this might also include a class name if that is something the
190    /// language natively considers to be part of the stack (for instance in Java).
191    #[serde(default, skip_serializing_if = "Option::is_none")]
192    pub module: Option<String>,
193    /// The name of the package that contains the frame.
194    ///
195    /// For instance this can be a dylib for native languages, the name of the jar
196    /// or .NET assembly.
197    #[serde(default, skip_serializing_if = "Option::is_none")]
198    pub package: Option<String>,
199    /// The filename (basename only).
200    #[serde(default, skip_serializing_if = "Option::is_none")]
201    pub filename: Option<String>,
202    /// If known the absolute path.
203    #[serde(default, skip_serializing_if = "Option::is_none")]
204    pub abs_path: Option<String>,
205    /// The line number if known.
206    #[serde(default, skip_serializing_if = "Option::is_none")]
207    pub lineno: Option<u64>,
208    /// The column number if known.
209    #[serde(default, skip_serializing_if = "Option::is_none")]
210    pub colno: Option<u64>,
211    /// The sources of the lines leading up to the current line.
212    #[serde(default, skip_serializing_if = "Vec::is_empty")]
213    pub pre_context: Vec<String>,
214    /// The current line as source.
215    #[serde(default, skip_serializing_if = "Option::is_none")]
216    pub context_line: Option<String>,
217    /// The sources of the lines after the current line.
218    #[serde(default, skip_serializing_if = "Vec::is_empty")]
219    pub post_context: Vec<String>,
220    /// In-app indicator.
221    #[serde(default, skip_serializing_if = "Option::is_none")]
222    pub in_app: Option<bool>,
223    /// Optional local variables.
224    #[serde(default, skip_serializing_if = "Map::is_empty")]
225    pub vars: Map<String, Value>,
226    /// If known the location of the image.
227    #[serde(default, skip_serializing_if = "Option::is_none")]
228    pub image_addr: Option<Addr>,
229    /// If known the location of the instruction.
230    #[serde(default, skip_serializing_if = "Option::is_none")]
231    pub instruction_addr: Option<Addr>,
232    /// If known the location of symbol.
233    #[serde(default, skip_serializing_if = "Option::is_none")]
234    pub symbol_addr: Option<Addr>,
235    /// Optionally changes the addressing mode. The default value is the same as
236    /// `"abs"` which means absolute referencing. This can also be set to
237    /// `"rel:DEBUG_ID"` or `"rel:IMAGE_INDEX"` to make addresses relative to an
238    /// object referenced by debug id or index. This for instance is necessary
239    /// for WASM processing as WASM does not use a unified address space.
240    #[serde(default, skip_serializing_if = "Option::is_none")]
241    pub addr_mode: Option<String>,
242}
243
244/// Represents template debug info.
245#[derive(Serialize, Deserialize, Default, Clone, Debug, PartialEq)]
246pub struct TemplateInfo {
247    /// The filename (basename only).
248    #[serde(default, skip_serializing_if = "Option::is_none")]
249    pub filename: Option<String>,
250    /// If known the absolute path.
251    #[serde(default, skip_serializing_if = "Option::is_none")]
252    pub abs_path: Option<String>,
253    /// The line number if known.
254    #[serde(default, skip_serializing_if = "Option::is_none")]
255    pub lineno: Option<u64>,
256    /// The column number if known.
257    #[serde(default, skip_serializing_if = "Option::is_none")]
258    pub colno: Option<u64>,
259    /// The sources of the lines leading up to the current line.
260    #[serde(default, skip_serializing_if = "Vec::is_empty")]
261    pub pre_context: Vec<String>,
262    /// The current line as source.
263    #[serde(default, skip_serializing_if = "Option::is_none")]
264    pub context_line: Option<String>,
265    /// The sources of the lines after the current line.
266    #[serde(default, skip_serializing_if = "Vec::is_empty")]
267    pub post_context: Vec<String>,
268}
269
270/// Represents a stacktrace.
271#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)]
272pub struct Stacktrace {
273    /// The list of frames in the stacktrace.
274    #[serde(default)]
275    pub frames: Vec<Frame>,
276    /// Optionally a segment of frames removed (`start`, `end`).
277    #[serde(default, skip_serializing_if = "Option::is_none")]
278    pub frames_omitted: Option<(u64, u64)>,
279    /// Optional register values of the thread.
280    #[serde(default, skip_serializing_if = "Map::is_empty")]
281    pub registers: Map<String, RegVal>,
282}
283
284impl Stacktrace {
285    /// Optionally creates a stacktrace from a list of stack frames.
286    pub fn from_frames_reversed(mut frames: Vec<Frame>) -> Option<Stacktrace> {
287        if frames.is_empty() {
288            None
289        } else {
290            frames.reverse();
291            Some(Stacktrace {
292                frames,
293                ..Default::default()
294            })
295        }
296    }
297}
298
299/// Represents a thread id.
300#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Ord, PartialOrd, Hash)]
301#[serde(untagged)]
302pub enum ThreadId {
303    /// Integer representation for the thread id
304    Int(u64),
305    /// String representation for the thread id
306    String(String),
307}
308
309impl Default for ThreadId {
310    fn default() -> ThreadId {
311        ThreadId::Int(0)
312    }
313}
314
315impl<'a> From<&'a str> for ThreadId {
316    fn from(id: &'a str) -> ThreadId {
317        ThreadId::String(id.to_string())
318    }
319}
320
321impl From<String> for ThreadId {
322    fn from(id: String) -> ThreadId {
323        ThreadId::String(id)
324    }
325}
326
327impl From<i64> for ThreadId {
328    fn from(id: i64) -> ThreadId {
329        ThreadId::Int(id as u64)
330    }
331}
332
333impl From<i32> for ThreadId {
334    fn from(id: i32) -> ThreadId {
335        ThreadId::Int(id as u64)
336    }
337}
338
339impl From<u32> for ThreadId {
340    fn from(id: u32) -> ThreadId {
341        ThreadId::Int(id as u64)
342    }
343}
344
345impl From<u16> for ThreadId {
346    fn from(id: u16) -> ThreadId {
347        ThreadId::Int(id as u64)
348    }
349}
350
351impl fmt::Display for ThreadId {
352    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
353        match *self {
354            ThreadId::Int(i) => write!(f, "{i}"),
355            ThreadId::String(ref s) => write!(f, "{s}"),
356        }
357    }
358}
359
360/// Represents an address.
361#[derive(Default, Debug, Clone, Copy, PartialEq, Eq, Ord, PartialOrd, Hash)]
362pub struct Addr(pub u64);
363
364impl Addr {
365    /// Returns `true` if this address is the null pointer.
366    pub fn is_null(&self) -> bool {
367        self.0 == 0
368    }
369}
370
371impl_hex_serde!(Addr, u64);
372
373impl From<u64> for Addr {
374    fn from(addr: u64) -> Addr {
375        Addr(addr)
376    }
377}
378
379impl From<i32> for Addr {
380    fn from(addr: i32) -> Addr {
381        Addr(addr as u64)
382    }
383}
384
385impl From<u32> for Addr {
386    fn from(addr: u32) -> Addr {
387        Addr(addr as u64)
388    }
389}
390
391impl From<usize> for Addr {
392    fn from(addr: usize) -> Addr {
393        Addr(addr as u64)
394    }
395}
396
397impl<T> From<*const T> for Addr {
398    fn from(addr: *const T) -> Addr {
399        Addr(addr as u64)
400    }
401}
402
403impl<T> From<*mut T> for Addr {
404    fn from(addr: *mut T) -> Addr {
405        Addr(addr as u64)
406    }
407}
408
409impl From<Addr> for u64 {
410    fn from(addr: Addr) -> Self {
411        addr.0
412    }
413}
414
415fn is_false(value: &bool) -> bool {
416    !*value
417}
418
419/// Represents a register value.
420#[derive(Default, Debug, Clone, Copy, PartialEq, Eq, Ord, PartialOrd, Hash)]
421pub struct RegVal(pub u64);
422
423impl_hex_serde!(RegVal, u64);
424
425impl From<u64> for RegVal {
426    fn from(addr: u64) -> RegVal {
427        RegVal(addr)
428    }
429}
430
431impl From<i32> for RegVal {
432    fn from(addr: i32) -> RegVal {
433        RegVal(addr as u64)
434    }
435}
436
437impl From<u32> for RegVal {
438    fn from(addr: u32) -> RegVal {
439        RegVal(addr as u64)
440    }
441}
442
443impl From<usize> for RegVal {
444    fn from(addr: usize) -> RegVal {
445        RegVal(addr as u64)
446    }
447}
448
449impl<T> From<*const T> for RegVal {
450    fn from(addr: *const T) -> RegVal {
451        RegVal(addr as u64)
452    }
453}
454
455impl<T> From<*mut T> for RegVal {
456    fn from(addr: *mut T) -> RegVal {
457        RegVal(addr as u64)
458    }
459}
460
461impl From<RegVal> for u64 {
462    fn from(reg: RegVal) -> Self {
463        reg.0
464    }
465}
466
467/// Represents a single thread.
468#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)]
469pub struct Thread {
470    /// The optional ID of the thread (usually an integer)
471    #[serde(default, skip_serializing_if = "Option::is_none")]
472    pub id: Option<ThreadId>,
473    /// The optional name of the thread.
474    #[serde(default, skip_serializing_if = "Option::is_none")]
475    pub name: Option<String>,
476    /// If the thread suspended or crashed a stacktrace can be
477    /// attached here.
478    #[serde(default, skip_serializing_if = "Option::is_none")]
479    pub stacktrace: Option<Stacktrace>,
480    /// Optional raw stacktrace.
481    #[serde(default, skip_serializing_if = "Option::is_none")]
482    pub raw_stacktrace: Option<Stacktrace>,
483    /// True if this is the crashed thread.
484    #[serde(default, skip_serializing_if = "is_false")]
485    pub crashed: bool,
486    /// Indicates that the thread was not suspended when the
487    /// event was created.
488    #[serde(default, skip_serializing_if = "is_false")]
489    pub current: bool,
490}
491
492/// POSIX signal with optional extended data.
493#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq, Eq)]
494pub struct CError {
495    /// The error code as specified by ISO C99, POSIX.1-2001 or POSIX.1-2008.
496    pub number: i32,
497    /// Optional name of the errno constant.
498    #[serde(default, skip_serializing_if = "Option::is_none")]
499    pub name: Option<String>,
500}
501
502impl From<i32> for CError {
503    fn from(number: i32) -> CError {
504        CError { number, name: None }
505    }
506}
507
508impl From<CError> for i32 {
509    fn from(err: CError) -> Self {
510        err.number
511    }
512}
513
514/// Mach exception information.
515#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq, Eq)]
516pub struct MachException {
517    /// The mach exception type.
518    pub exception: i32,
519    /// The mach exception code.
520    pub code: u64,
521    /// The mach exception subcode.
522    pub subcode: u64,
523    /// Optional name of the mach exception.
524    #[serde(default, skip_serializing_if = "Option::is_none")]
525    pub name: Option<String>,
526}
527
528/// POSIX signal with optional extended data.
529#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq, Eq)]
530pub struct PosixSignal {
531    /// The POSIX signal number.
532    pub number: i32,
533    /// An optional signal code present on Apple systems.
534    #[serde(default, skip_serializing_if = "Option::is_none")]
535    pub code: Option<i32>,
536    /// Optional name of the errno constant.
537    #[serde(default, skip_serializing_if = "Option::is_none")]
538    pub name: Option<String>,
539    /// Optional name of the errno constant.
540    #[serde(default, skip_serializing_if = "Option::is_none")]
541    pub code_name: Option<String>,
542}
543
544impl From<i32> for PosixSignal {
545    fn from(number: i32) -> PosixSignal {
546        PosixSignal {
547            number,
548            code: None,
549            name: None,
550            code_name: None,
551        }
552    }
553}
554
555impl From<(i32, i32)> for PosixSignal {
556    fn from(tuple: (i32, i32)) -> PosixSignal {
557        let (number, code) = tuple;
558        PosixSignal {
559            number,
560            code: Some(code),
561            name: None,
562            code_name: None,
563        }
564    }
565}
566
567impl From<PosixSignal> for i32 {
568    fn from(sig: PosixSignal) -> Self {
569        sig.number
570    }
571}
572
573/// Operating system or runtime meta information to an exception mechanism.
574#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)]
575pub struct MechanismMeta {
576    /// Optional ISO C standard error code.
577    #[serde(default, skip_serializing_if = "Option::is_none")]
578    pub errno: Option<CError>,
579    /// Optional POSIX signal number.
580    #[serde(default, skip_serializing_if = "Option::is_none")]
581    pub signal: Option<PosixSignal>,
582    /// Optional mach exception information.
583    #[serde(default, skip_serializing_if = "Option::is_none")]
584    pub mach_exception: Option<MachException>,
585}
586
587impl MechanismMeta {
588    fn is_empty(&self) -> bool {
589        self.errno.is_none() && self.signal.is_none() && self.mach_exception.is_none()
590    }
591}
592
593/// Represents a single exception.
594#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)]
595pub struct Mechanism {
596    /// The mechanism type identifier.
597    #[serde(rename = "type")]
598    pub ty: String,
599    /// Human readable detail description.
600    #[serde(default, skip_serializing_if = "Option::is_none")]
601    pub description: Option<String>,
602    /// An optional link to online resources describing this error.
603    #[serde(default, skip_serializing_if = "Option::is_none")]
604    pub help_link: Option<Url>,
605    /// An optional flag indicating whether this exception was handled.
606    #[serde(default, skip_serializing_if = "Option::is_none")]
607    pub handled: Option<bool>,
608    /// An optional flag indicating a synthetic exception.
609    #[serde(default, skip_serializing_if = "Option::is_none")]
610    pub synthetic: Option<bool>,
611    /// Additional attributes depending on the mechanism type.
612    #[serde(default, skip_serializing_if = "Map::is_empty")]
613    pub data: Map<String, Value>,
614    /// Operating system or runtime meta information.
615    #[serde(default, skip_serializing_if = "MechanismMeta::is_empty")]
616    pub meta: MechanismMeta,
617}
618
619/// Represents a single exception.
620#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)]
621pub struct Exception {
622    /// The type of the exception.
623    #[serde(rename = "type")]
624    pub ty: String,
625    /// The optional value of the exception.
626    #[serde(skip_serializing_if = "Option::is_none")]
627    pub value: Option<String>,
628    /// An optional module for this exception.
629    #[serde(default, skip_serializing_if = "Option::is_none")]
630    pub module: Option<String>,
631    /// Optionally the stacktrace.
632    #[serde(default, skip_serializing_if = "Option::is_none")]
633    pub stacktrace: Option<Stacktrace>,
634    /// An optional raw stacktrace.
635    #[serde(default, skip_serializing_if = "Option::is_none")]
636    pub raw_stacktrace: Option<Stacktrace>,
637    /// Optional identifier referring to a thread.
638    #[serde(default, skip_serializing_if = "Option::is_none")]
639    pub thread_id: Option<ThreadId>,
640    /// The mechanism of the exception including OS specific exception values.
641    #[serde(default, skip_serializing_if = "Option::is_none")]
642    pub mechanism: Option<Mechanism>,
643}
644
645/// An error used when parsing `Level`.
646#[derive(Debug, Error)]
647#[error("invalid level")]
648pub struct ParseLevelError;
649
650/// Represents the level of severity of an event or breadcrumb.
651#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
652pub enum Level {
653    /// Indicates very spammy debug information.
654    Debug,
655    /// Informational messages.
656    #[default]
657    Info,
658    /// A warning.
659    Warning,
660    /// An error.
661    Error,
662    /// Similar to error but indicates a critical event that usually causes a shutdown.
663    Fatal,
664}
665
666impl str::FromStr for Level {
667    type Err = ParseLevelError;
668
669    fn from_str(string: &str) -> Result<Level, Self::Err> {
670        Ok(match string {
671            "debug" => Level::Debug,
672            "info" | "log" => Level::Info,
673            "warning" => Level::Warning,
674            "error" => Level::Error,
675            "fatal" => Level::Fatal,
676            _ => return Err(ParseLevelError),
677        })
678    }
679}
680
681impl fmt::Display for Level {
682    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
683        match *self {
684            Level::Debug => write!(f, "debug"),
685            Level::Info => write!(f, "info"),
686            Level::Warning => write!(f, "warning"),
687            Level::Error => write!(f, "error"),
688            Level::Fatal => write!(f, "fatal"),
689        }
690    }
691}
692
693impl Level {
694    /// A quick way to check if the level is `debug`.
695    pub fn is_debug(&self) -> bool {
696        *self == Level::Debug
697    }
698
699    /// A quick way to check if the level is `info`.
700    pub fn is_info(&self) -> bool {
701        *self == Level::Info
702    }
703
704    /// A quick way to check if the level is `warning`.
705    pub fn is_warning(&self) -> bool {
706        *self == Level::Warning
707    }
708
709    /// A quick way to check if the level is `error`.
710    pub fn is_error(&self) -> bool {
711        *self == Level::Error
712    }
713
714    /// A quick way to check if the level is `fatal`.
715    pub fn is_fatal(&self) -> bool {
716        *self == Level::Fatal
717    }
718}
719
720impl_str_serde!(Level);
721
722mod breadcrumb {
723    use super::*;
724
725    pub fn default_type() -> String {
726        "default".to_string()
727    }
728
729    pub fn is_default_type(ty: &str) -> bool {
730        ty == "default"
731    }
732
733    pub fn default_level() -> Level {
734        Level::Info
735    }
736}
737
738/// Represents a single breadcrumb.
739#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
740pub struct Breadcrumb {
741    /// The timestamp of the breadcrumb.  This is required.
742    #[serde(default = "SystemTime::now", with = "ts_seconds_float")]
743    pub timestamp: SystemTime,
744    /// The type of the breadcrumb.
745    #[serde(
746        rename = "type",
747        default = "breadcrumb::default_type",
748        skip_serializing_if = "breadcrumb::is_default_type"
749    )]
750    pub ty: String,
751    /// The optional category of the breadcrumb.
752    #[serde(default, skip_serializing_if = "Option::is_none")]
753    pub category: Option<String>,
754    /// The non optional level of the breadcrumb.  It
755    /// defaults to info.
756    #[serde(
757        default = "breadcrumb::default_level",
758        skip_serializing_if = "Level::is_info"
759    )]
760    pub level: Level,
761    /// An optional human readbale message for the breadcrumb.
762    #[serde(default, skip_serializing_if = "Option::is_none")]
763    pub message: Option<String>,
764    /// Arbitrary breadcrumb data that should be send along.
765    #[serde(default, skip_serializing_if = "Map::is_empty")]
766    pub data: Map<String, Value>,
767}
768
769impl Default for Breadcrumb {
770    fn default() -> Breadcrumb {
771        Breadcrumb {
772            timestamp: SystemTime::now(),
773            ty: breadcrumb::default_type(),
774            category: Default::default(),
775            level: breadcrumb::default_level(),
776            message: Default::default(),
777            data: Default::default(),
778        }
779    }
780}
781
782/// An IP address, either IPv4, IPv6 or Auto.
783#[derive(Debug, Clone, Copy, PartialEq, Eq, Ord, PartialOrd, Hash, Default)]
784pub enum IpAddress {
785    /// The IP address needs to be inferred from the user's context.
786    #[default]
787    Auto,
788    /// The exact given IP address (v4 or v6).
789    Exact(IpAddr),
790}
791
792impl PartialEq<IpAddr> for IpAddress {
793    fn eq(&self, other: &IpAddr) -> bool {
794        match *self {
795            IpAddress::Auto => false,
796            IpAddress::Exact(ref addr) => addr == other,
797        }
798    }
799}
800
801impl cmp::PartialOrd<IpAddr> for IpAddress {
802    fn partial_cmp(&self, other: &IpAddr) -> Option<cmp::Ordering> {
803        match *self {
804            IpAddress::Auto => None,
805            IpAddress::Exact(ref addr) => addr.partial_cmp(other),
806        }
807    }
808}
809
810impl fmt::Display for IpAddress {
811    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
812        match *self {
813            IpAddress::Auto => write!(f, "{{{{auto}}}}"),
814            IpAddress::Exact(ref addr) => write!(f, "{addr}"),
815        }
816    }
817}
818
819impl From<IpAddr> for IpAddress {
820    fn from(addr: IpAddr) -> IpAddress {
821        IpAddress::Exact(addr)
822    }
823}
824
825impl str::FromStr for IpAddress {
826    type Err = AddrParseError;
827
828    fn from_str(string: &str) -> Result<IpAddress, AddrParseError> {
829        match string {
830            "{{auto}}" => Ok(IpAddress::Auto),
831            other => other.parse().map(IpAddress::Exact),
832        }
833    }
834}
835
836impl_str_serde!(IpAddress);
837
838/// Represents user info.
839#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)]
840pub struct User {
841    /// The ID of the user.
842    #[serde(default, skip_serializing_if = "Option::is_none")]
843    pub id: Option<String>,
844    /// The email address of the user.
845    #[serde(default, skip_serializing_if = "Option::is_none")]
846    pub email: Option<String>,
847    /// The remote ip address of the user.
848    #[serde(default, skip_serializing_if = "Option::is_none")]
849    pub ip_address: Option<IpAddress>,
850    /// A human readable username of the user.
851    #[serde(default, skip_serializing_if = "Option::is_none")]
852    pub username: Option<String>,
853    /// Additional arbitrary fields for forwards compatibility.
854    #[serde(flatten)]
855    pub other: Map<String, Value>,
856}
857
858/// Represents http request data.
859#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)]
860pub struct Request {
861    /// The current URL of the request.
862    #[serde(default, skip_serializing_if = "Option::is_none")]
863    pub url: Option<Url>,
864    /// The HTTP request method.
865    #[serde(default, skip_serializing_if = "Option::is_none")]
866    pub method: Option<String>,
867    /// Optionally some associated request data (human readable)
868    // XXX: this makes absolutely no sense because of unicode
869    #[serde(default, skip_serializing_if = "Option::is_none")]
870    pub data: Option<String>,
871    /// Optionally the encoded query string.
872    #[serde(default, skip_serializing_if = "Option::is_none")]
873    pub query_string: Option<String>,
874    /// An encoded cookie string if available.
875    #[serde(default, skip_serializing_if = "Option::is_none")]
876    pub cookies: Option<String>,
877    /// HTTP request headers.
878    #[serde(default, skip_serializing_if = "Map::is_empty")]
879    pub headers: Map<String, String>,
880    /// Optionally a CGI/WSGI etc. environment dictionary.
881    #[serde(default, skip_serializing_if = "Map::is_empty")]
882    pub env: Map<String, String>,
883}
884
885/// Holds information about the system SDK.
886///
887/// This is relevant for iOS and other platforms that have a system
888/// SDK.  Not to be confused with the client SDK.
889#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
890pub struct SystemSdkInfo {
891    /// The internal name of the SDK
892    pub sdk_name: String,
893    /// the major version of the SDK as integer or 0
894    pub version_major: u32,
895    /// the minor version of the SDK as integer or 0
896    pub version_minor: u32,
897    /// the patch version of the SDK as integer or 0
898    pub version_patchlevel: u32,
899}
900
901/// Represents a debug image.
902#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
903#[serde(rename_all = "snake_case", tag = "type")]
904pub enum DebugImage {
905    /// Apple debug images (machos).  This is currently also used for
906    /// non apple platforms with similar debug setups.
907    Apple(AppleDebugImage),
908    /// Symbolic (new style) debug infos.
909    Symbolic(SymbolicDebugImage),
910    /// A reference to a proguard debug file.
911    Proguard(ProguardDebugImage),
912    /// Image used for WebAssembly. Their structure is identical to other native
913    /// images.
914    Wasm(WasmDebugImage),
915}
916
917impl DebugImage {
918    /// Returns the name of the type on sentry.
919    pub fn type_name(&self) -> &str {
920        match *self {
921            DebugImage::Apple(..) => "apple",
922            DebugImage::Symbolic(..) => "symbolic",
923            DebugImage::Proguard(..) => "proguard",
924            DebugImage::Wasm(..) => "wasm",
925        }
926    }
927}
928
929macro_rules! into_debug_image {
930    ($kind:ident, $ty:ty) => {
931        impl From<$ty> for DebugImage {
932            fn from(data: $ty) -> DebugImage {
933                DebugImage::$kind(data)
934            }
935        }
936    };
937}
938
939/// Represents an apple debug image in the debug meta.
940#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
941pub struct AppleDebugImage {
942    /// The name of the debug image (usually filename)
943    pub name: String,
944    /// The optional CPU architecture of the debug image.
945    pub arch: Option<String>,
946    /// Alternatively a macho cpu type.
947    pub cpu_type: Option<u32>,
948    /// Alternatively a macho cpu subtype.
949    pub cpu_subtype: Option<u32>,
950    /// The starting address of the image.
951    pub image_addr: Addr,
952    /// The size of the image in bytes.
953    pub image_size: u64,
954    /// The address where the image is loaded at runtime.
955    #[serde(default, skip_serializing_if = "Addr::is_null")]
956    pub image_vmaddr: Addr,
957    /// The unique UUID of the image.
958    pub uuid: Uuid,
959}
960
961/// Represents a symbolic debug image.
962#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
963pub struct SymbolicDebugImage {
964    /// Path and name of the image file (required).
965    ///
966    /// The absolute path to the dynamic library or executable. This helps to locate the file if it is missing on Sentry.
967    /// This is also called `code_file`.
968    pub name: String,
969    /// The optional CPU architecture of the debug image.
970    pub arch: Option<String>,
971    /// Starting memory address of the image (required).
972    ///
973    /// Memory address, at which the image is mounted in the virtual address space of the process.
974    pub image_addr: Addr,
975    /// Size of the image in bytes (required).
976    ///
977    /// The size of the image in virtual memory.
978    pub image_size: u64,
979    /// Loading address in virtual memory.
980    ///
981    /// Preferred load address of the image in virtual memory, as declared in the headers of the
982    /// image. When loading an image, the operating system may still choose to place it at a
983    /// different address.
984    ///
985    /// Symbols and addresses in the native image are always relative to the start of the image and do not consider the preferred load address. It is merely a hint to the loader.
986    #[serde(default, skip_serializing_if = "Addr::is_null")]
987    pub image_vmaddr: Addr,
988    /// Unique debug identifier of the image.
989    ///
990    /// This is also called `debug_id`.
991    pub id: DebugId,
992
993    /// Optional identifier of the code file.
994    #[serde(default, skip_serializing_if = "Option::is_none")]
995    pub code_id: Option<CodeId>,
996    /// Path and name of the debug companion file.
997    #[serde(default, skip_serializing_if = "Option::is_none")]
998    pub debug_file: Option<String>,
999}
1000
1001/// Represents a proguard mapping file reference.
1002#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
1003pub struct ProguardDebugImage {
1004    /// The UUID of the associated proguard file.
1005    pub uuid: Uuid,
1006}
1007
1008/// Represents a WebAssembly debug image.
1009#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
1010pub struct WasmDebugImage {
1011    /// The name of the debug image (usually filename)
1012    pub name: String,
1013    /// Identifier of the dynamic library or executable.
1014    pub debug_id: Uuid,
1015    /// Name or absolute URL to the WASM file containing debug information for
1016    /// this image. This value might be required to retrieve debug files from
1017    /// certain symbol servers. This should correspond to the externalized URL
1018    /// pulled from the external_debug_info custom section.
1019    #[serde(default, skip_serializing_if = "Option::is_none")]
1020    pub debug_file: Option<String>,
1021    /// Identifier of the WASM file. It is the value of the build_id custom
1022    /// section formatted as HEX string.
1023    #[serde(default, skip_serializing_if = "Option::is_none")]
1024    pub code_id: Option<String>,
1025    /// The absolute URL to the wasm file. This helps to locate the file if it
1026    /// is missing on Sentry.
1027    pub code_file: String,
1028}
1029
1030into_debug_image!(Apple, AppleDebugImage);
1031into_debug_image!(Symbolic, SymbolicDebugImage);
1032into_debug_image!(Proguard, ProguardDebugImage);
1033into_debug_image!(Wasm, WasmDebugImage);
1034
1035/// Represents debug meta information.
1036#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq)]
1037pub struct DebugMeta {
1038    /// Optional system SDK information.
1039    #[serde(default, skip_serializing_if = "Option::is_none")]
1040    pub sdk_info: Option<SystemSdkInfo>,
1041    /// A list of debug information files.
1042    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1043    pub images: Vec<DebugImage>,
1044}
1045
1046impl DebugMeta {
1047    /// Returns true if the debug meta is empty.
1048    ///
1049    /// This is used by the serializer to entirely skip the section.
1050    pub fn is_empty(&self) -> bool {
1051        self.sdk_info.is_none() && self.images.is_empty()
1052    }
1053}
1054
1055/// Information on the SDK client.
1056#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
1057pub struct ClientSdkInfo {
1058    /// The name of the SDK.
1059    pub name: String,
1060    /// The version of the SDK.
1061    pub version: String,
1062    /// An optional list of integrations that are enabled in this SDK.
1063    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1064    pub integrations: Vec<String>,
1065    /// An optional list of packages that are installed in the SDK's environment.
1066    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1067    pub packages: Vec<ClientSdkPackage>,
1068}
1069
1070/// Represents an installed package relevant to the SDK.
1071#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
1072pub struct ClientSdkPackage {
1073    /// The name of the package installed.
1074    pub name: String,
1075    /// The version of the package.
1076    pub version: String,
1077}
1078
1079/// Typed contextual data.
1080///
1081/// Types like `OsContext` can be directly converted with `.into()`
1082/// to `Context`.
1083#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
1084#[serde(rename_all = "snake_case", tag = "type")]
1085#[non_exhaustive]
1086pub enum Context {
1087    /// Device data.
1088    Device(Box<DeviceContext>),
1089    /// Operating system data.
1090    Os(Box<OsContext>),
1091    /// Runtime data.
1092    Runtime(Box<RuntimeContext>),
1093    /// Application data.
1094    App(Box<AppContext>),
1095    /// Web browser data.
1096    Browser(Box<BrowserContext>),
1097    /// Tracing data.
1098    Trace(Box<TraceContext>),
1099    /// GPU data.
1100    Gpu(Box<GpuContext>),
1101    /// OpenTelemetry data.
1102    Otel(Box<OtelContext>),
1103    /// Generic other context data.
1104    #[serde(rename = "unknown")]
1105    Other(Map<String, Value>),
1106}
1107
1108impl Context {
1109    /// Returns the name of the type for sentry.
1110    pub fn type_name(&self) -> &str {
1111        match *self {
1112            Context::Device(..) => "device",
1113            Context::Os(..) => "os",
1114            Context::Runtime(..) => "runtime",
1115            Context::App(..) => "app",
1116            Context::Browser(..) => "browser",
1117            Context::Trace(..) => "trace",
1118            Context::Gpu(..) => "gpu",
1119            Context::Otel(..) => "otel",
1120            Context::Other(..) => "unknown",
1121        }
1122    }
1123}
1124
1125/// Optional device screen orientation
1126#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Hash)]
1127#[serde(rename_all = "lowercase")]
1128pub enum Orientation {
1129    /// Portrait device orientation.
1130    Portrait,
1131    /// Landscape device orientation.
1132    Landscape,
1133}
1134
1135/// Holds device information.
1136#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
1137pub struct DeviceContext {
1138    /// The name of the device.
1139    #[serde(default, skip_serializing_if = "Option::is_none")]
1140    pub name: Option<String>,
1141    /// The family of the device model.
1142    #[serde(default, skip_serializing_if = "Option::is_none")]
1143    pub family: Option<String>,
1144    /// The device model (human readable).
1145    #[serde(default, skip_serializing_if = "Option::is_none")]
1146    pub model: Option<String>,
1147    /// The device model (internal identifier).
1148    #[serde(default, skip_serializing_if = "Option::is_none")]
1149    pub model_id: Option<String>,
1150    /// The native cpu architecture of the device.
1151    #[serde(default, skip_serializing_if = "Option::is_none")]
1152    pub arch: Option<String>,
1153    /// The current battery level (0-100).
1154    #[serde(default, skip_serializing_if = "Option::is_none")]
1155    pub battery_level: Option<f32>,
1156    /// The current screen orientation.
1157    #[serde(default, skip_serializing_if = "Option::is_none")]
1158    pub orientation: Option<Orientation>,
1159    /// Simulator/prod indicator.
1160    #[serde(default, skip_serializing_if = "Option::is_none")]
1161    pub simulator: Option<bool>,
1162    /// Total memory available in byts.
1163    #[serde(default, skip_serializing_if = "Option::is_none")]
1164    pub memory_size: Option<u64>,
1165    /// How much memory is still available in bytes.
1166    #[serde(default, skip_serializing_if = "Option::is_none")]
1167    pub free_memory: Option<u64>,
1168    /// How much memory is usable for the app in bytes.
1169    #[serde(default, skip_serializing_if = "Option::is_none")]
1170    pub usable_memory: Option<u64>,
1171    /// Total storage size of the device in bytes.
1172    #[serde(default, skip_serializing_if = "Option::is_none")]
1173    pub storage_size: Option<u64>,
1174    /// How much storage is free in bytes.
1175    #[serde(default, skip_serializing_if = "Option::is_none")]
1176    pub free_storage: Option<u64>,
1177    /// Total size of the attached external storage in bytes (eg: android SDK card).
1178    #[serde(default, skip_serializing_if = "Option::is_none")]
1179    pub external_storage_size: Option<u64>,
1180    /// Free size of the attached external storage in bytes (eg: android SDK card).
1181    #[serde(default, skip_serializing_if = "Option::is_none")]
1182    pub external_free_storage: Option<u64>,
1183    /// Optionally an indicator when the device was booted.
1184    #[serde(
1185        default,
1186        skip_serializing_if = "Option::is_none",
1187        with = "ts_rfc3339_opt"
1188    )]
1189    pub boot_time: Option<SystemTime>,
1190    /// The timezone of the device.
1191    #[serde(default, skip_serializing_if = "Option::is_none")]
1192    pub timezone: Option<String>,
1193    /// Additional arbitrary fields for forwards compatibility.
1194    #[serde(flatten)]
1195    pub other: Map<String, Value>,
1196}
1197
1198/// Holds operating system information.
1199#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
1200pub struct OsContext {
1201    /// The name of the operating system.
1202    #[serde(default, skip_serializing_if = "Option::is_none")]
1203    pub name: Option<String>,
1204    /// The version of the operating system.
1205    #[serde(default, skip_serializing_if = "Option::is_none")]
1206    pub version: Option<String>,
1207    /// The internal build number of the operating system.
1208    #[serde(default, skip_serializing_if = "Option::is_none")]
1209    pub build: Option<String>,
1210    /// The current kernel version.
1211    #[serde(default, skip_serializing_if = "Option::is_none")]
1212    pub kernel_version: Option<String>,
1213    /// An indicator if the os is rooted (mobile mostly).
1214    #[serde(default, skip_serializing_if = "Option::is_none")]
1215    pub rooted: Option<bool>,
1216    /// Additional arbitrary fields for forwards compatibility.
1217    #[serde(flatten)]
1218    pub other: Map<String, Value>,
1219}
1220
1221/// Holds information about the runtime.
1222#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
1223pub struct RuntimeContext {
1224    /// The name of the runtime (for instance JVM).
1225    #[serde(default, skip_serializing_if = "Option::is_none")]
1226    pub name: Option<String>,
1227    /// The version of the runtime.
1228    #[serde(default, skip_serializing_if = "Option::is_none")]
1229    pub version: Option<String>,
1230    /// Additional arbitrary fields for forwards compatibility.
1231    #[serde(flatten)]
1232    pub other: Map<String, Value>,
1233}
1234
1235/// Holds app information.
1236#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
1237pub struct AppContext {
1238    /// Optional start time of the app.
1239    #[serde(
1240        default,
1241        skip_serializing_if = "Option::is_none",
1242        with = "ts_rfc3339_opt"
1243    )]
1244    pub app_start_time: Option<SystemTime>,
1245    /// Optional device app hash (app specific device ID)
1246    #[serde(default, skip_serializing_if = "Option::is_none")]
1247    pub device_app_hash: Option<String>,
1248    /// Optional build identicator.
1249    #[serde(default, skip_serializing_if = "Option::is_none")]
1250    pub build_type: Option<String>,
1251    /// Optional app identifier (dotted bundle id).
1252    #[serde(default, skip_serializing_if = "Option::is_none")]
1253    pub app_identifier: Option<String>,
1254    /// Application name as it appears on the platform.
1255    #[serde(default, skip_serializing_if = "Option::is_none")]
1256    pub app_name: Option<String>,
1257    /// Application version as it appears on the platform.
1258    #[serde(default, skip_serializing_if = "Option::is_none")]
1259    pub app_version: Option<String>,
1260    /// Internal build ID as it appears on the platform.
1261    #[serde(default, skip_serializing_if = "Option::is_none")]
1262    pub app_build: Option<String>,
1263    /// Additional arbitrary fields for forwards compatibility.
1264    #[serde(flatten)]
1265    pub other: Map<String, Value>,
1266}
1267
1268/// Holds information about the web browser.
1269#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
1270pub struct BrowserContext {
1271    /// The name of the browser (for instance "Chrome").
1272    #[serde(default, skip_serializing_if = "Option::is_none")]
1273    pub name: Option<String>,
1274    /// The version of the browser.
1275    #[serde(default, skip_serializing_if = "Option::is_none")]
1276    pub version: Option<String>,
1277    /// Additional arbitrary fields for forwards compatibility.
1278    #[serde(flatten)]
1279    pub other: Map<String, Value>,
1280}
1281
1282/// GPU context describes the GPU of the device.
1283#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
1284pub struct GpuContext {
1285    /// The name of the graphics device.
1286    pub name: String,
1287    /// The Version of the graphics device.
1288    #[serde(default, skip_serializing_if = "Option::is_none")]
1289    pub version: Option<String>,
1290    /// The version of the graphic device driver.
1291    #[serde(default, skip_serializing_if = "Option::is_none")]
1292    pub driver_version: Option<String>,
1293    /// The PCI identifier of the graphics device.
1294    #[serde(default, skip_serializing_if = "Option::is_none")]
1295    pub id: Option<String>,
1296    /// The PCI vendor identifier of the graphics device.
1297    #[serde(default, skip_serializing_if = "Option::is_none")]
1298    pub vendor_id: Option<String>,
1299    /// The vendor name as reported by the graphics device.
1300    #[serde(default, skip_serializing_if = "Option::is_none")]
1301    pub vendor_name: Option<String>,
1302    /// The total GPU memory available in Megabytes.
1303    #[serde(default, skip_serializing_if = "Option::is_none")]
1304    pub memory_size: Option<u32>,
1305    /// The device low-level API type. Examples: "Apple Metal" or "Direct3D11"
1306    #[serde(default, skip_serializing_if = "Option::is_none")]
1307    pub api_type: Option<String>,
1308    /// Whether the GPU has multi-threaded rendering or not.
1309    #[serde(default, skip_serializing_if = "Option::is_none")]
1310    pub multi_threaded_rendering: Option<bool>,
1311    /// The Non-Power-Of-Two-Support support.
1312    #[serde(default, skip_serializing_if = "Option::is_none")]
1313    pub npot_support: Option<bool>,
1314    /// Largest size of a texture that is supported by the graphics hardware.
1315    #[serde(default, skip_serializing_if = "Option::is_none")]
1316    pub max_texture_size: Option<u32>,
1317    /// Approximate "shader capability" level of the graphics device. For example,
1318    /// `Shader Model 2.0, OpenGL ES 3.0, Metal / OpenGL ES 3.1, 27 (unknown)`.
1319    #[serde(default, skip_serializing_if = "Option::is_none")]
1320    pub graphics_shader_level: Option<String>,
1321    /// Is GPU draw call instancing supported?
1322    #[serde(default, skip_serializing_if = "Option::is_none")]
1323    pub supports_draw_call_instancing: Option<bool>,
1324    /// Is ray tracing available on the device?
1325    #[serde(default, skip_serializing_if = "Option::is_none")]
1326    pub supports_ray_tracing: Option<bool>,
1327    /// Are compute shaders available on the device?
1328    #[serde(default, skip_serializing_if = "Option::is_none")]
1329    pub supports_compute_shaders: Option<bool>,
1330    /// Are geometry shaders available on the device?
1331    #[serde(default, skip_serializing_if = "Option::is_none")]
1332    pub supports_geometry_shaders: Option<bool>,
1333    /// Additional arbitrary fields for forwards compatibility.
1334    #[serde(flatten)]
1335    pub other: Map<String, Value>,
1336}
1337
1338/// OpenTelemetry context
1339#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
1340pub struct OtelContext {
1341    /// OpenTelemetry [general
1342    /// attributes](https://opentelemetry.io/docs/specs/semconv/general/attributes/).
1343    #[serde(default, skip_serializing_if = "Map::is_empty")]
1344    pub attributes: Map<String, Value>,
1345    /// OpenTelemetry [resource attributes](https://opentelemetry.io/docs/specs/semconv/resource/),
1346    /// describing the entity producing telemetry.
1347    #[serde(default, skip_serializing_if = "Map::is_empty")]
1348    pub resource: Map<String, Value>,
1349    /// Additional arbitrary fields for forwards compatibility.
1350    #[serde(flatten)]
1351    pub other: Map<String, Value>,
1352}
1353
1354/// Holds the identifier for a Span
1355#[derive(Serialize, Deserialize, Debug, Copy, Clone, Eq, PartialEq, Hash)]
1356#[serde(try_from = "String", into = "String")]
1357pub struct SpanId([u8; 8]);
1358
1359impl Default for SpanId {
1360    fn default() -> Self {
1361        Self(rand::random())
1362    }
1363}
1364
1365impl fmt::Display for SpanId {
1366    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1367        write!(fmt, "{}", hex::encode(self.0))
1368    }
1369}
1370
1371impl From<SpanId> for String {
1372    fn from(span_id: SpanId) -> Self {
1373        span_id.to_string()
1374    }
1375}
1376
1377impl str::FromStr for SpanId {
1378    type Err = hex::FromHexError;
1379
1380    fn from_str(input: &str) -> Result<Self, Self::Err> {
1381        let mut buf = [0; 8];
1382        hex::decode_to_slice(input, &mut buf)?;
1383        Ok(Self(buf))
1384    }
1385}
1386
1387impl TryFrom<String> for SpanId {
1388    type Error = hex::FromHexError;
1389
1390    fn try_from(value: String) -> Result<Self, Self::Error> {
1391        value.parse()
1392    }
1393}
1394
1395impl From<[u8; 8]> for SpanId {
1396    fn from(value: [u8; 8]) -> Self {
1397        Self(value)
1398    }
1399}
1400
1401/// Holds the identifier for a Trace
1402#[derive(Serialize, Deserialize, Debug, Copy, Clone, Eq, PartialEq, Hash)]
1403#[serde(try_from = "String", into = "String")]
1404pub struct TraceId([u8; 16]);
1405
1406impl Default for TraceId {
1407    fn default() -> Self {
1408        Self(rand::random())
1409    }
1410}
1411
1412impl fmt::Display for TraceId {
1413    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1414        write!(fmt, "{}", hex::encode(self.0))
1415    }
1416}
1417
1418impl From<TraceId> for String {
1419    fn from(trace_id: TraceId) -> Self {
1420        trace_id.to_string()
1421    }
1422}
1423
1424impl str::FromStr for TraceId {
1425    type Err = hex::FromHexError;
1426
1427    fn from_str(input: &str) -> Result<Self, Self::Err> {
1428        let mut buf = [0; 16];
1429        hex::decode_to_slice(input, &mut buf)?;
1430        Ok(Self(buf))
1431    }
1432}
1433
1434impl TryFrom<String> for TraceId {
1435    type Error = hex::FromHexError;
1436
1437    fn try_from(value: String) -> Result<Self, Self::Error> {
1438        value.parse()
1439    }
1440}
1441
1442impl From<[u8; 16]> for TraceId {
1443    fn from(value: [u8; 16]) -> Self {
1444        Self(value)
1445    }
1446}
1447
1448/// Holds information about a tracing event.
1449#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
1450pub struct TraceContext {
1451    /// The ID of the trace event
1452    #[serde(default)]
1453    pub span_id: SpanId,
1454    /// Determines which trace the transaction belongs to.
1455    #[serde(default)]
1456    pub trace_id: TraceId,
1457    /// Determines the parent of this transaction if any.
1458    #[serde(default, skip_serializing_if = "Option::is_none")]
1459    pub parent_span_id: Option<SpanId>,
1460    /// Short code identifying the type of operation the transaction is measuring.
1461    #[serde(default, skip_serializing_if = "Option::is_none")]
1462    pub op: Option<String>,
1463    /// Human readable detail description.
1464    #[serde(default, skip_serializing_if = "Option::is_none")]
1465    pub description: Option<String>,
1466    /// Describes the status of the span (e.g. `ok`, `cancelled`, etc.)
1467    #[serde(default, skip_serializing_if = "Option::is_none")]
1468    pub status: Option<SpanStatus>,
1469    /// Optional data attributes to be associated with the transaction.
1470    #[serde(default, skip_serializing_if = "Map::is_empty")]
1471    pub data: Map<String, Value>,
1472}
1473
1474macro_rules! into_context {
1475    ($kind:ident, $ty:ty) => {
1476        impl From<$ty> for Context {
1477            fn from(data: $ty) -> Self {
1478                Context::$kind(Box::new(data))
1479            }
1480        }
1481    };
1482}
1483
1484into_context!(App, AppContext);
1485into_context!(Device, DeviceContext);
1486into_context!(Os, OsContext);
1487into_context!(Runtime, RuntimeContext);
1488into_context!(Browser, BrowserContext);
1489into_context!(Trace, TraceContext);
1490into_context!(Gpu, GpuContext);
1491into_context!(Otel, OtelContext);
1492
1493const INFERABLE_CONTEXTS: &[&str] = &[
1494    "device", "os", "runtime", "app", "browser", "trace", "gpu", "otel",
1495];
1496
1497struct ContextsVisitor;
1498
1499impl<'de> de::Visitor<'de> for ContextsVisitor {
1500    type Value = Map<String, Context>;
1501
1502    fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
1503        formatter.write_str("contexts object")
1504    }
1505
1506    fn visit_map<A>(self, mut access: A) -> Result<Self::Value, A::Error>
1507    where
1508        A: de::MapAccess<'de>,
1509    {
1510        let mut map: Map<String, Context> = Map::new();
1511
1512        while let Some((key, mut value)) = access.next_entry::<String, Value>()? {
1513            let typed_value = value
1514                .as_object_mut()
1515                .map(|ctx| {
1516                    if !ctx.contains_key("type") {
1517                        let type_key = if INFERABLE_CONTEXTS.contains(&key.as_str()) {
1518                            key.clone().into()
1519                        } else {
1520                            Value::String("unknown".into())
1521                        };
1522                        ctx.insert(String::from("type"), type_key);
1523                    }
1524                    ctx.to_owned()
1525                })
1526                .ok_or_else(|| de::Error::custom("expected valid `context` object"))?;
1527
1528            match serde_json::from_value(serde_json::to_value(typed_value).unwrap()) {
1529                Ok(context) => {
1530                    map.insert(key, context);
1531                }
1532                Err(e) => return Err(de::Error::custom(e.to_string())),
1533            }
1534        }
1535
1536        Ok(map)
1537    }
1538}
1539
1540fn deserialize_contexts<'de, D>(deserializer: D) -> Result<Map<String, Context>, D::Error>
1541where
1542    D: Deserializer<'de>,
1543{
1544    deserializer.deserialize_map(ContextsVisitor {})
1545}
1546
1547mod event {
1548    use super::*;
1549
1550    pub fn default_id() -> Uuid {
1551        crate::random_uuid()
1552    }
1553
1554    pub fn serialize_id<S: Serializer>(uuid: &Uuid, serializer: S) -> Result<S::Ok, S::Error> {
1555        serializer.serialize_some(&uuid.as_simple().to_string())
1556    }
1557
1558    pub fn default_level() -> Level {
1559        Level::Error
1560    }
1561
1562    pub fn default_platform() -> Cow<'static, str> {
1563        Cow::Borrowed("other")
1564    }
1565
1566    pub fn is_default_platform(value: &str) -> bool {
1567        value == "other"
1568    }
1569
1570    static DEFAULT_FINGERPRINT: &[Cow<'static, str>] = &[Cow::Borrowed("{{ default }}")];
1571
1572    pub fn default_fingerprint<'a>() -> Cow<'a, [Cow<'a, str>]> {
1573        Cow::Borrowed(DEFAULT_FINGERPRINT)
1574    }
1575
1576    pub fn is_default_fingerprint(fp: &[Cow<'_, str>]) -> bool {
1577        fp.len() == 1 && ((fp)[0] == "{{ default }}" || (fp)[0] == "{{default}}")
1578    }
1579}
1580
1581/// Represents a full event for Sentry.
1582#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
1583pub struct Event<'a> {
1584    /// The ID of the event
1585    #[serde(default = "event::default_id", serialize_with = "event::serialize_id")]
1586    pub event_id: Uuid,
1587    /// The level of the event (defaults to error)
1588    #[serde(
1589        default = "event::default_level",
1590        skip_serializing_if = "Level::is_error"
1591    )]
1592    pub level: Level,
1593    /// An optional fingerprint configuration to override the default.
1594    #[serde(
1595        default = "event::default_fingerprint",
1596        skip_serializing_if = "event::is_default_fingerprint"
1597    )]
1598    pub fingerprint: Cow<'a, [Cow<'a, str>]>,
1599    /// The culprit of the event.
1600    #[serde(default, skip_serializing_if = "Option::is_none")]
1601    pub culprit: Option<String>,
1602    /// The transaction name of the event.
1603    #[serde(default, skip_serializing_if = "Option::is_none")]
1604    pub transaction: Option<String>,
1605    /// A message to be sent with the event.
1606    #[serde(default, skip_serializing_if = "Option::is_none")]
1607    pub message: Option<String>,
1608    /// Optionally a log entry that can be used instead of the message for
1609    /// more complex cases.
1610    #[serde(default, skip_serializing_if = "Option::is_none")]
1611    pub logentry: Option<LogEntry>,
1612    /// Optionally the name of the logger that created this event.
1613    #[serde(default, skip_serializing_if = "Option::is_none")]
1614    pub logger: Option<String>,
1615    /// Optionally a name to version mapping of installed modules.
1616    #[serde(default, skip_serializing_if = "Map::is_empty")]
1617    pub modules: Map<String, String>,
1618    /// A platform identifier for this event.
1619    #[serde(
1620        default = "event::default_platform",
1621        skip_serializing_if = "event::is_default_platform"
1622    )]
1623    pub platform: Cow<'a, str>,
1624    /// The timestamp of when the event was created.
1625    ///
1626    /// This can be set to `None` in which case the server will set a timestamp.
1627    #[serde(default = "SystemTime::now", with = "ts_seconds_float")]
1628    pub timestamp: SystemTime,
1629    /// Optionally the server (or device) name of this event.
1630    #[serde(default, skip_serializing_if = "Option::is_none")]
1631    pub server_name: Option<Cow<'a, str>>,
1632    /// A release identifier.
1633    #[serde(default, skip_serializing_if = "Option::is_none")]
1634    pub release: Option<Cow<'a, str>>,
1635    /// An optional distribution identifier.
1636    #[serde(default, skip_serializing_if = "Option::is_none")]
1637    pub dist: Option<Cow<'a, str>>,
1638    /// An optional environment identifier.
1639    #[serde(default, skip_serializing_if = "Option::is_none")]
1640    pub environment: Option<Cow<'a, str>>,
1641    /// Optionally user data to be sent along.
1642    #[serde(default, skip_serializing_if = "Option::is_none")]
1643    pub user: Option<User>,
1644    /// Optionally HTTP request data to be sent along.
1645    #[serde(default, skip_serializing_if = "Option::is_none")]
1646    pub request: Option<Request>,
1647    /// Optional contexts.
1648    #[serde(
1649        default,
1650        skip_serializing_if = "Map::is_empty",
1651        deserialize_with = "deserialize_contexts"
1652    )]
1653    pub contexts: Map<String, Context>,
1654    /// List of breadcrumbs to send along.
1655    #[serde(default, skip_serializing_if = "Values::is_empty")]
1656    pub breadcrumbs: Values<Breadcrumb>,
1657    /// Exceptions to be attached (one or multiple if chained).
1658    #[serde(default, skip_serializing_if = "Values::is_empty")]
1659    pub exception: Values<Exception>,
1660    /// A single stacktrace (deprecated)
1661    #[serde(default, skip_serializing_if = "Option::is_none")]
1662    pub stacktrace: Option<Stacktrace>,
1663    /// Simplified template error location info
1664    #[serde(default, skip_serializing_if = "Option::is_none")]
1665    pub template: Option<TemplateInfo>,
1666    /// A list of threads.
1667    #[serde(default, skip_serializing_if = "Values::is_empty")]
1668    pub threads: Values<Thread>,
1669    /// Optional tags to be attached to the event.
1670    #[serde(default, skip_serializing_if = "Map::is_empty")]
1671    pub tags: Map<String, String>,
1672    /// Optional extra information to be sent with the event.
1673    #[serde(default, skip_serializing_if = "Map::is_empty")]
1674    pub extra: Map<String, Value>,
1675    /// Debug meta information.
1676    #[serde(default, skip_serializing_if = "DebugMeta::is_empty")]
1677    pub debug_meta: Cow<'a, DebugMeta>,
1678    /// SDK metadata
1679    #[serde(default, skip_serializing_if = "Option::is_none")]
1680    pub sdk: Option<Cow<'a, ClientSdkInfo>>,
1681}
1682
1683impl Default for Event<'_> {
1684    fn default() -> Self {
1685        Event {
1686            event_id: event::default_id(),
1687            level: event::default_level(),
1688            fingerprint: event::default_fingerprint(),
1689            culprit: Default::default(),
1690            transaction: Default::default(),
1691            message: Default::default(),
1692            logentry: Default::default(),
1693            logger: Default::default(),
1694            modules: Default::default(),
1695            platform: event::default_platform(),
1696            timestamp: SystemTime::now(),
1697            server_name: Default::default(),
1698            release: Default::default(),
1699            dist: Default::default(),
1700            environment: Default::default(),
1701            user: Default::default(),
1702            request: Default::default(),
1703            contexts: Default::default(),
1704            breadcrumbs: Default::default(),
1705            exception: Default::default(),
1706            stacktrace: Default::default(),
1707            template: Default::default(),
1708            threads: Default::default(),
1709            tags: Default::default(),
1710            extra: Default::default(),
1711            debug_meta: Default::default(),
1712            sdk: Default::default(),
1713        }
1714    }
1715}
1716
1717impl<'a> Event<'a> {
1718    /// Creates a new event with the current timestamp and random id.
1719    pub fn new() -> Event<'a> {
1720        Default::default()
1721    }
1722
1723    /// Creates a fully owned version of the event.
1724    pub fn into_owned(self) -> Event<'static> {
1725        Event {
1726            event_id: self.event_id,
1727            level: self.level,
1728            fingerprint: Cow::Owned(
1729                self.fingerprint
1730                    .iter()
1731                    .map(|x| Cow::Owned(x.to_string()))
1732                    .collect(),
1733            ),
1734            culprit: self.culprit,
1735            transaction: self.transaction,
1736            message: self.message,
1737            logentry: self.logentry,
1738            logger: self.logger,
1739            modules: self.modules,
1740            platform: Cow::Owned(self.platform.into_owned()),
1741            timestamp: self.timestamp,
1742            server_name: self.server_name.map(|x| Cow::Owned(x.into_owned())),
1743            release: self.release.map(|x| Cow::Owned(x.into_owned())),
1744            dist: self.dist.map(|x| Cow::Owned(x.into_owned())),
1745            environment: self.environment.map(|x| Cow::Owned(x.into_owned())),
1746            user: self.user,
1747            request: self.request,
1748            contexts: self.contexts,
1749            breadcrumbs: self.breadcrumbs,
1750            exception: self.exception,
1751            stacktrace: self.stacktrace,
1752            template: self.template,
1753            threads: self.threads,
1754            tags: self.tags,
1755            extra: self.extra,
1756            debug_meta: Cow::Owned(self.debug_meta.into_owned()),
1757            sdk: self.sdk.map(|x| Cow::Owned(x.into_owned())),
1758        }
1759    }
1760}
1761
1762impl fmt::Display for Event<'_> {
1763    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1764        write!(
1765            f,
1766            "Event(id: {}, ts: {})",
1767            self.event_id,
1768            crate::utils::to_rfc3339(&self.timestamp)
1769        )
1770    }
1771}
1772
1773/// Represents a tracing span.
1774#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
1775pub struct Span {
1776    /// The ID of the span
1777    #[serde(default)]
1778    pub span_id: SpanId,
1779    /// Determines which trace the span belongs to.
1780    #[serde(default)]
1781    pub trace_id: TraceId,
1782    /// Determines the parent of this span, if any.
1783    #[serde(default, skip_serializing_if = "Option::is_none")]
1784    pub parent_span_id: Option<SpanId>,
1785    /// Determines whether this span is generated in the same process as its parent, if any.
1786    #[serde(default, skip_serializing_if = "Option::is_none")]
1787    pub same_process_as_parent: Option<bool>,
1788    /// Short code identifying the type of operation the span is measuring.
1789    #[serde(default, skip_serializing_if = "Option::is_none")]
1790    pub op: Option<String>,
1791    /// Longer description of the span's operation, which uniquely identifies the span
1792    /// but is consistent across instances of the span.
1793    #[serde(default, skip_serializing_if = "Option::is_none")]
1794    pub description: Option<String>,
1795    /// The timestamp at the measuring of the span finished.
1796    #[serde(
1797        default,
1798        skip_serializing_if = "Option::is_none",
1799        with = "ts_rfc3339_opt"
1800    )]
1801    pub timestamp: Option<SystemTime>,
1802    /// The timestamp at the measuring of the span started.
1803    #[serde(default = "SystemTime::now", with = "ts_seconds_float")]
1804    pub start_timestamp: SystemTime,
1805    /// Describes the status of the span (e.g. `ok`, `cancelled`, etc.)
1806    #[serde(default, skip_serializing_if = "Option::is_none")]
1807    pub status: Option<SpanStatus>,
1808    /// Optional tags to be attached to the span.
1809    #[serde(default, skip_serializing_if = "Map::is_empty")]
1810    pub tags: Map<String, String>,
1811    /// Optional extra information to be sent with the span.
1812    #[serde(default, skip_serializing_if = "Map::is_empty")]
1813    pub data: Map<String, Value>,
1814}
1815
1816impl Default for Span {
1817    fn default() -> Self {
1818        Span {
1819            span_id: Default::default(),
1820            trace_id: Default::default(),
1821            timestamp: Default::default(),
1822            tags: Default::default(),
1823            start_timestamp: SystemTime::now(),
1824            description: Default::default(),
1825            status: Default::default(),
1826            parent_span_id: Default::default(),
1827            same_process_as_parent: Default::default(),
1828            op: Default::default(),
1829            data: Default::default(),
1830        }
1831    }
1832}
1833
1834impl Span {
1835    /// Creates a new span with the current timestamp and random id.
1836    pub fn new() -> Span {
1837        Default::default()
1838    }
1839
1840    /// Finalizes the span with the provided timestamp.
1841    pub fn finish_with_timestamp(&mut self, timestamp: SystemTime) {
1842        self.timestamp = Some(timestamp);
1843    }
1844
1845    /// Finalizes the span.
1846    pub fn finish(&mut self) {
1847        self.timestamp = Some(SystemTime::now());
1848    }
1849}
1850
1851impl fmt::Display for Span {
1852    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1853        write!(
1854            f,
1855            "Span(id: {}, ts: {})",
1856            self.span_id,
1857            crate::utils::to_rfc3339(&self.start_timestamp)
1858        )
1859    }
1860}
1861
1862/// An error used when parsing `SpanStatus`.
1863#[derive(Debug, Error)]
1864#[error("invalid status")]
1865pub struct ParseStatusError;
1866
1867/// The status of a Span.
1868#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Eq, Hash)]
1869#[non_exhaustive]
1870pub enum SpanStatus {
1871    /// The operation completed successfully.
1872    #[serde(rename = "ok")]
1873    Ok,
1874    /// Deadline expired before operation could complete.
1875    #[serde(rename = "deadline_exceeded")]
1876    DeadlineExceeded,
1877    /// 401 Unauthorized (actually does mean unauthenticated according to RFC 7235)
1878    #[serde(rename = "unauthenticated")]
1879    Unauthenticated,
1880    /// 403 Forbidden
1881    #[serde(rename = "permission_denied")]
1882    PermissionDenied,
1883    /// 404 Not Found. Some requested entity (file or directory) was not found.
1884    #[serde(rename = "not_found")]
1885    NotFound,
1886    /// 429 Too Many Requests
1887    #[serde(rename = "resource_exhausted")]
1888    ResourceExhausted,
1889    /// Client specified an invalid argument. 4xx.
1890    #[serde(rename = "invalid_argument")]
1891    InvalidArgument,
1892    /// 501 Not Implemented
1893    #[serde(rename = "unimplemented")]
1894    Unimplemented,
1895    /// 503 Service Unavailable
1896    #[serde(rename = "unavailable")]
1897    Unavailable,
1898    /// Other/generic 5xx.
1899    #[serde(rename = "internal_error")]
1900    InternalError,
1901    /// Unknown. Any non-standard HTTP status code.
1902    #[serde(rename = "unknown_error")]
1903    UnknownError,
1904    /// The operation was cancelled (typically by the user).
1905    #[serde(rename = "cancelled")]
1906    Cancelled,
1907    /// Already exists (409)
1908    #[serde(rename = "already_exists")]
1909    AlreadyExists,
1910    /// Operation was rejected because the system is not in a state required for the operation's
1911    #[serde(rename = "failed_precondition")]
1912    FailedPrecondition,
1913    /// The operation was aborted, typically due to a concurrency issue.
1914    #[serde(rename = "aborted")]
1915    Aborted,
1916    /// Operation was attempted past the valid range.
1917    #[serde(rename = "out_of_range")]
1918    OutOfRange,
1919    /// Unrecoverable data loss or corruption
1920    #[serde(rename = "data_loss")]
1921    DataLoss,
1922}
1923
1924impl str::FromStr for SpanStatus {
1925    type Err = ParseStatusError;
1926
1927    fn from_str(s: &str) -> Result<SpanStatus, Self::Err> {
1928        Ok(match s {
1929            "ok" => SpanStatus::Ok,
1930            "deadline_exceeded" => SpanStatus::DeadlineExceeded,
1931            "unauthenticated" => SpanStatus::Unauthenticated,
1932            "permission_denied" => SpanStatus::PermissionDenied,
1933            "not_found" => SpanStatus::NotFound,
1934            "resource_exhausted" => SpanStatus::ResourceExhausted,
1935            "invalid_argument" => SpanStatus::InvalidArgument,
1936            "unimplemented" => SpanStatus::Unimplemented,
1937            "unavailable" => SpanStatus::Unavailable,
1938            "internal_error" => SpanStatus::InternalError,
1939            "unknown_error" => SpanStatus::UnknownError,
1940            "cancelled" => SpanStatus::Cancelled,
1941            "already_exists" => SpanStatus::AlreadyExists,
1942            "failed_precondition" => SpanStatus::FailedPrecondition,
1943            "aborted" => SpanStatus::Aborted,
1944            "out_of_range" => SpanStatus::OutOfRange,
1945            "data_loss" => SpanStatus::DataLoss,
1946            _ => return Err(ParseStatusError),
1947        })
1948    }
1949}
1950
1951impl fmt::Display for SpanStatus {
1952    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1953        match self {
1954            SpanStatus::Ok => write!(f, "ok"),
1955            SpanStatus::DeadlineExceeded => write!(f, "deadline_exceeded"),
1956            SpanStatus::Unauthenticated => write!(f, "unauthenticated"),
1957            SpanStatus::PermissionDenied => write!(f, "permission_denied"),
1958            SpanStatus::NotFound => write!(f, "not_found"),
1959            SpanStatus::ResourceExhausted => write!(f, "resource_exhausted"),
1960            SpanStatus::InvalidArgument => write!(f, "invalid_argument"),
1961            SpanStatus::Unimplemented => write!(f, "unimplemented"),
1962            SpanStatus::Unavailable => write!(f, "unavailable"),
1963            SpanStatus::InternalError => write!(f, "internal_error"),
1964            SpanStatus::UnknownError => write!(f, "unknown_error"),
1965            SpanStatus::Cancelled => write!(f, "cancelled"),
1966            SpanStatus::AlreadyExists => write!(f, "already_exists"),
1967            SpanStatus::FailedPrecondition => write!(f, "failed_precondition"),
1968            SpanStatus::Aborted => write!(f, "aborted"),
1969            SpanStatus::OutOfRange => write!(f, "out_of_range"),
1970            SpanStatus::DataLoss => write!(f, "data_loss"),
1971        }
1972    }
1973}
1974
1975/// Represents a tracing transaction.
1976#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
1977pub struct Transaction<'a> {
1978    /// The ID of the event
1979    #[serde(default = "event::default_id", serialize_with = "event::serialize_id")]
1980    pub event_id: Uuid,
1981    /// The transaction name.
1982    #[serde(
1983        rename = "transaction",
1984        default,
1985        skip_serializing_if = "Option::is_none"
1986    )]
1987    pub name: Option<String>,
1988    /// A release identifier.
1989    #[serde(default, skip_serializing_if = "Option::is_none")]
1990    pub release: Option<Cow<'a, str>>,
1991    /// An optional environment identifier.
1992    #[serde(default, skip_serializing_if = "Option::is_none")]
1993    pub environment: Option<Cow<'a, str>>,
1994    /// Optionally user data to be sent along.
1995    #[serde(default, skip_serializing_if = "Option::is_none")]
1996    pub user: Option<User>,
1997    /// Optional tags to be attached to the event.
1998    #[serde(default, skip_serializing_if = "Map::is_empty")]
1999    pub tags: Map<String, String>,
2000    /// Optional extra information to be sent with the event.
2001    #[serde(default, skip_serializing_if = "Map::is_empty")]
2002    pub extra: Map<String, Value>,
2003    /// SDK metadata
2004    #[serde(default, skip_serializing_if = "Option::is_none")]
2005    pub sdk: Option<Cow<'a, ClientSdkInfo>>,
2006    /// A platform identifier for this event.
2007    #[serde(
2008        default = "event::default_platform",
2009        skip_serializing_if = "event::is_default_platform"
2010    )]
2011    pub platform: Cow<'a, str>,
2012    /// The end time of the transaction.
2013    #[serde(
2014        default,
2015        skip_serializing_if = "Option::is_none",
2016        with = "ts_rfc3339_opt"
2017    )]
2018    pub timestamp: Option<SystemTime>,
2019    /// The start time of the transaction.
2020    #[serde(default = "SystemTime::now", with = "ts_seconds_float")]
2021    pub start_timestamp: SystemTime,
2022    /// The collection of finished spans part of this transaction.
2023    pub spans: Vec<Span>,
2024    /// Optional contexts.
2025    #[serde(
2026        default,
2027        skip_serializing_if = "Map::is_empty",
2028        deserialize_with = "deserialize_contexts"
2029    )]
2030    pub contexts: Map<String, Context>,
2031    /// Optionally HTTP request data to be sent along.
2032    #[serde(default, skip_serializing_if = "Option::is_none")]
2033    pub request: Option<Request>,
2034    /// Optionally the server (or device) name of this event.
2035    #[serde(default, skip_serializing_if = "Option::is_none")]
2036    pub server_name: Option<Cow<'a, str>>,
2037}
2038
2039impl Default for Transaction<'_> {
2040    fn default() -> Self {
2041        Transaction {
2042            event_id: event::default_id(),
2043            name: Default::default(),
2044            user: Default::default(),
2045            tags: Default::default(),
2046            extra: Default::default(),
2047            release: Default::default(),
2048            environment: Default::default(),
2049            sdk: Default::default(),
2050            platform: event::default_platform(),
2051            timestamp: Default::default(),
2052            start_timestamp: SystemTime::now(),
2053            spans: Default::default(),
2054            contexts: Default::default(),
2055            request: Default::default(),
2056            server_name: Default::default(),
2057        }
2058    }
2059}
2060
2061impl<'a> Transaction<'a> {
2062    /// Creates a new span transaction the current timestamp and random id.
2063    pub fn new() -> Transaction<'a> {
2064        Default::default()
2065    }
2066
2067    /// Creates a fully owned version of the transaction.
2068    pub fn into_owned(self) -> Transaction<'static> {
2069        Transaction {
2070            event_id: self.event_id,
2071            name: self.name,
2072            user: self.user,
2073            tags: self.tags,
2074            extra: self.extra,
2075            release: self.release.map(|x| Cow::Owned(x.into_owned())),
2076            environment: self.environment.map(|x| Cow::Owned(x.into_owned())),
2077            sdk: self.sdk.map(|x| Cow::Owned(x.into_owned())),
2078            platform: Cow::Owned(self.platform.into_owned()),
2079            timestamp: self.timestamp,
2080            start_timestamp: self.start_timestamp,
2081            spans: self.spans,
2082            contexts: self.contexts,
2083            request: self.request,
2084            server_name: self.server_name.map(|x| Cow::Owned(x.into_owned())),
2085        }
2086    }
2087
2088    /// Finalizes the transaction to be dispatched.
2089    pub fn finish(&mut self) {
2090        self.timestamp = Some(SystemTime::now());
2091    }
2092
2093    /// Finalizes the transaction to be dispatched with the given end timestamp.
2094    pub fn finish_with_timestamp(&mut self, timestamp: SystemTime) {
2095        self.timestamp = Some(timestamp);
2096    }
2097}
2098
2099impl fmt::Display for Transaction<'_> {
2100    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2101        write!(
2102            f,
2103            "Transaction(id: {}, ts: {})",
2104            self.event_id,
2105            crate::utils::to_rfc3339(&self.start_timestamp)
2106        )
2107    }
2108}