relay_base_schema/
data_category.rs

1//! Defines the [`DataCategory`] type that classifies data Relay can handle.
2
3use std::fmt;
4use std::str::FromStr;
5
6use serde::{Deserialize, Serialize};
7
8use crate::events::EventType;
9
10/// An error that occurs if a number cannot be converted into a [`DataCategory`].
11#[derive(Debug, PartialEq, thiserror::Error)]
12#[error("Unknown numeric data category {0} can not be converted into a DataCategory.")]
13pub struct UnknownDataCategory(pub u8);
14
15/// Classifies the type of data that is being ingested.
16#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd, Deserialize, Serialize)]
17#[serde(rename_all = "snake_case")]
18#[repr(i8)]
19pub enum DataCategory {
20    /// Reserved and unused.
21    ///
22    /// SDK rate limiting behavior: ignore.
23    Default = 0,
24    /// Error events and Events with an `event_type` not explicitly listed below.
25    ///
26    /// SDK rate limiting behavior: apply to the entire envelope if it contains an item type `event`.
27    Error = 1,
28    /// Transaction events.
29    ///
30    /// SDK rate limiting behavior: apply to the entire envelope if it contains an item `transaction`.
31    Transaction = 2,
32    /// Events with an event type of `csp`, `hpkp`, `expectct` and `expectstaple`.
33    ///
34    /// SDK rate limiting behavior: ignore.
35    Security = 3,
36    /// An attachment. Quantity is the size of the attachment in bytes.
37    ///
38    /// SDK rate limiting behavior: apply to all attachments.
39    Attachment = 4,
40    /// Session updates. Quantity is the number of updates in the batch.
41    ///
42    /// SDK rate limiting behavior: apply to all sessions and session aggregates.
43    Session = 5,
44    /// Profile
45    ///
46    /// This is the category for processed profiles (all profiles, whether or not we store them).
47    ///
48    /// SDK rate limiting behavior: apply to all profiles.
49    Profile = 6,
50    /// Session Replays
51    ///
52    /// SDK rate limiting behavior: apply to all Session Replay data.
53    Replay = 7,
54    /// DEPRECATED: A transaction for which metrics were extracted.
55    ///
56    /// This category is now obsolete because the `Transaction` variant will represent
57    /// processed transactions from now on.
58    ///
59    /// SDK rate limiting behavior: ignore.
60    TransactionProcessed = 8,
61    /// Indexed transaction events.
62    ///
63    /// This is the category for transaction payloads that were accepted and stored in full. In
64    /// contrast, `transaction` only guarantees that metrics have been accepted for the transaction.
65    ///
66    /// SDK rate limiting behavior: ignore.
67    TransactionIndexed = 9,
68    /// Monitor check-ins.
69    ///
70    /// SDK rate limiting behavior: apply to items of type `check_in`.
71    Monitor = 10,
72    /// Indexed Profile
73    ///
74    /// This is the category for indexed profiles that will be stored later.
75    ///
76    /// SDK rate limiting behavior: ignore.
77    ProfileIndexed = 11,
78    /// Span
79    ///
80    /// This is the category for spans from which we extracted metrics from.
81    ///
82    /// SDK rate limiting behavior: apply to spans that are not sent in a transaction.
83    Span = 12,
84    /// Monitor Seat
85    ///
86    /// Represents a monitor job that has scheduled monitor checkins. The seats are not ingested
87    /// but we define it here to prevent clashing values since this data category enumeration
88    /// is also used outside of Relay via the Python package.
89    ///
90    /// SDK rate limiting behavior: ignore.
91    MonitorSeat = 13,
92    /// User Feedback
93    ///
94    /// Represents a User Feedback processed.
95    /// Currently standardized on name UserReportV2 to avoid clashing with the old UserReport.
96    /// TODO(jferg): Rename this to UserFeedback once old UserReport is deprecated.
97    ///
98    /// SDK rate limiting behavior: apply to items of type 'feedback'.
99    UserReportV2 = 14,
100    /// Metric buckets.
101    ///
102    /// SDK rate limiting behavior: apply to `statsd` and `metrics` items.
103    MetricBucket = 15,
104    /// SpanIndexed
105    ///
106    /// This is the category for spans we store in full.
107    ///
108    /// SDK rate limiting behavior: ignore.
109    SpanIndexed = 16,
110    /// ProfileDuration
111    ///
112    /// This data category is used to count the number of milliseconds per indexed profile chunk,
113    /// excluding UI profile chunks.
114    ///
115    /// SDK rate limiting behavior: apply to profile chunks.
116    ProfileDuration = 17,
117    /// ProfileChunk
118    ///
119    /// This is a count of profile chunks received. It will not be used for billing but will be
120    /// useful for customers to track what's being dropped.
121    ///
122    /// SDK rate limiting behavior: apply to profile chunks.
123    ProfileChunk = 18,
124    /// MetricSecond
125    ///
126    /// Reserved by billing to summarize the bucketed product of metric volume
127    /// and metric cardinality. Defined here so as not to clash with future
128    /// categories.
129    ///
130    /// SDK rate limiting behavior: ignore.
131    MetricSecond = 19,
132    /// Replay Video
133    ///
134    /// This is the data category for Session Replays produced via a video recording.
135    ///
136    /// SDK rate limiting behavior: ignore.
137    DoNotUseReplayVideo = 20,
138    /// This is the data category for Uptime monitors.
139    ///
140    /// SDK rate limiting behavior: ignore.
141    Uptime = 21,
142    /// Counts the number of individual attachments, as opposed to the number of bytes in an attachment.
143    ///
144    /// SDK rate limiting behavior: apply to attachments.
145    AttachmentItem = 22,
146    /// LogItem
147    ///
148    /// This is the category for logs for which we store the count log events for users for measuring
149    /// missing breadcrumbs, and count of logs for rate limiting purposes.
150    ///
151    /// SDK rate limiting behavior: apply to logs.
152    LogItem = 23,
153    /// LogByte
154    ///
155    /// This is the category for logs for which we store log event total bytes for users.
156    ///
157    /// SDK rate limiting behavior: apply to logs.
158    LogByte = 24,
159    /// Profile duration of a UI profile.
160    ///
161    /// This data category is used to count the number of milliseconds per indexed UI profile
162    /// chunk.
163    ///
164    /// See also: [`Self::ProfileDuration`]
165    ///
166    /// SDK rate limiting behavior: apply to profile chunks.
167    ProfileDurationUi = 25,
168    /// UI Profile Chunk.
169    ///
170    /// This data category is used to count the number of milliseconds per indexed UI profile
171    /// chunk.
172    ///
173    /// See also: [`Self::ProfileChunk`]
174    ///
175    /// SDK rate limiting behavior: apply to profile chunks.
176    ProfileChunkUi = 26,
177    /// This is the data category to count Seer Autofix run events.
178    ///
179    /// SDK rate limiting behavior: ignore.
180    SeerAutofix = 27,
181    /// This is the data category to count Seer Scanner run events.
182    ///
183    /// SDK rate limiting behavior: ignore.
184    SeerScanner = 28,
185    /// PreventUser
186    ///
187    /// This is the data category to count the number of assigned Prevent Users.
188    ///
189    /// SDK rate limiting behavior: ignore.
190    PreventUser = 29,
191    /// PreventReview
192    ///
193    /// This is the data category to count the number of Prevent review events.
194    ///
195    /// SDK rate limiting behavior: ignore.
196    PreventReview = 30,
197    /// Size analysis
198    ///
199    /// This is the data category to count the number of size analyses performed.
200    /// 'Size analysis' a static binary analysis of a preprod build artifact
201    /// (e.g. the .apk of an Android app or MacOS .app).
202    /// When enabled there will typically be one such analysis per uploaded artifact.
203    ///
204    /// SDK rate limiting behavior: ignore.
205    SizeAnalysis = 31,
206    /// InstallableBuild
207    ///
208    /// This is the data category to count the number of installable builds.
209    /// It counts the number of artifacts uploaded *not* the number of times the
210    /// artifacts are downloaded for installation.
211    /// When enabled there will typically be one 'InstallableBuild' per uploaded artifact.
212    ///
213    /// SDK rate limiting behavior: ignore.
214    InstallableBuild = 32,
215    /// TraceMetric
216    ///
217    /// This is the data category to count the number of trace metric items.
218    TraceMetric = 33,
219    //
220    // IMPORTANT: After adding a new entry to DataCategory, go to the `relay-cabi` subfolder and run
221    // `make header` to regenerate the C-binding. This allows using the data category from Python.
222    // Rerun this step every time the **code name** of the variant is updated.
223    //
224    /// Any other data category not known by this Relay.
225    #[serde(other)]
226    Unknown = -1,
227}
228
229impl DataCategory {
230    /// Returns the data category corresponding to the given name.
231    pub fn from_name(string: &str) -> Self {
232        // TODO: This should probably use serde.
233        match string {
234            "default" => Self::Default,
235            "error" => Self::Error,
236            "transaction" => Self::Transaction,
237            "security" => Self::Security,
238            "attachment" => Self::Attachment,
239            "session" => Self::Session,
240            "profile" => Self::Profile,
241            "profile_indexed" => Self::ProfileIndexed,
242            "replay" => Self::Replay,
243            "transaction_processed" => Self::TransactionProcessed,
244            "transaction_indexed" => Self::TransactionIndexed,
245            "monitor" => Self::Monitor,
246            "span" => Self::Span,
247            "log_item" => Self::LogItem,
248            "log_byte" => Self::LogByte,
249            "monitor_seat" => Self::MonitorSeat,
250            "feedback" => Self::UserReportV2,
251            "user_report_v2" => Self::UserReportV2,
252            "metric_bucket" => Self::MetricBucket,
253            "span_indexed" => Self::SpanIndexed,
254            "profile_duration" => Self::ProfileDuration,
255            "profile_duration_ui" => Self::ProfileDurationUi,
256            "profile_chunk" => Self::ProfileChunk,
257            "profile_chunk_ui" => Self::ProfileChunkUi,
258            "metric_second" => Self::MetricSecond,
259            "replay_video" => Self::DoNotUseReplayVideo,
260            "uptime" => Self::Uptime,
261            "attachment_item" => Self::AttachmentItem,
262            "seer_autofix" => Self::SeerAutofix,
263            "seer_scanner" => Self::SeerScanner,
264            "prevent_user" => Self::PreventUser,
265            "prevent_review" => Self::PreventReview,
266            "size_analysis" => Self::SizeAnalysis,
267            "installable_build" => Self::InstallableBuild,
268            "trace_metric" => Self::TraceMetric,
269            _ => Self::Unknown,
270        }
271    }
272
273    /// Returns the canonical name of this data category.
274    pub fn name(self) -> &'static str {
275        // TODO: This should probably use serde.
276        match self {
277            Self::Default => "default",
278            Self::Error => "error",
279            Self::Transaction => "transaction",
280            Self::Security => "security",
281            Self::Attachment => "attachment",
282            Self::Session => "session",
283            Self::Profile => "profile",
284            Self::ProfileIndexed => "profile_indexed",
285            Self::Replay => "replay",
286            Self::DoNotUseReplayVideo => "replay_video",
287            Self::TransactionProcessed => "transaction_processed",
288            Self::TransactionIndexed => "transaction_indexed",
289            Self::Monitor => "monitor",
290            Self::Span => "span",
291            Self::LogItem => "log_item",
292            Self::LogByte => "log_byte",
293            Self::MonitorSeat => "monitor_seat",
294            Self::UserReportV2 => "feedback",
295            Self::MetricBucket => "metric_bucket",
296            Self::SpanIndexed => "span_indexed",
297            Self::ProfileDuration => "profile_duration",
298            Self::ProfileDurationUi => "profile_duration_ui",
299            Self::ProfileChunk => "profile_chunk",
300            Self::ProfileChunkUi => "profile_chunk_ui",
301            Self::MetricSecond => "metric_second",
302            Self::Uptime => "uptime",
303            Self::AttachmentItem => "attachment_item",
304            Self::SeerAutofix => "seer_autofix",
305            Self::SeerScanner => "seer_scanner",
306            Self::PreventUser => "prevent_user",
307            Self::PreventReview => "prevent_review",
308            Self::SizeAnalysis => "size_analysis",
309            Self::InstallableBuild => "installable_build",
310            Self::TraceMetric => "trace_metric",
311            Self::Unknown => "unknown",
312        }
313    }
314
315    /// Returns true if the DataCategory refers to an error (i.e an error event).
316    pub fn is_error(self) -> bool {
317        matches!(self, Self::Error | Self::Default | Self::Security)
318    }
319
320    /// Returns the numeric value for this outcome.
321    pub fn value(self) -> Option<u8> {
322        // negative values (Internal and Unknown) cannot be sent as
323        // outcomes (internally so!)
324        (self as i8).try_into().ok()
325    }
326
327    /// Returns a dedicated category for indexing if this data can be converted to metrics.
328    ///
329    /// This returns `None` for most data categories.
330    pub fn index_category(self) -> Option<Self> {
331        match self {
332            Self::Transaction => Some(Self::TransactionIndexed),
333            Self::Span => Some(Self::SpanIndexed),
334            Self::Profile => Some(Self::ProfileIndexed),
335            _ => None,
336        }
337    }
338
339    /// Returns `true` if this data category is an indexed data category.
340    pub fn is_indexed(self) -> bool {
341        matches!(
342            self,
343            Self::TransactionIndexed | Self::SpanIndexed | Self::ProfileIndexed
344        )
345    }
346}
347
348impl fmt::Display for DataCategory {
349    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
350        write!(f, "{}", self.name())
351    }
352}
353
354impl FromStr for DataCategory {
355    type Err = ();
356
357    fn from_str(string: &str) -> Result<Self, Self::Err> {
358        Ok(Self::from_name(string))
359    }
360}
361
362impl From<EventType> for DataCategory {
363    fn from(ty: EventType) -> Self {
364        match ty {
365            EventType::Default | EventType::Error | EventType::Nel => Self::Error,
366            EventType::Transaction => Self::Transaction,
367            EventType::Csp | EventType::Hpkp | EventType::ExpectCt | EventType::ExpectStaple => {
368                Self::Security
369            }
370            EventType::UserReportV2 => Self::UserReportV2,
371        }
372    }
373}
374
375impl TryFrom<u8> for DataCategory {
376    type Error = UnknownDataCategory;
377
378    fn try_from(value: u8) -> Result<Self, UnknownDataCategory> {
379        match value {
380            0 => Ok(Self::Default),
381            1 => Ok(Self::Error),
382            2 => Ok(Self::Transaction),
383            3 => Ok(Self::Security),
384            4 => Ok(Self::Attachment),
385            5 => Ok(Self::Session),
386            6 => Ok(Self::Profile),
387            7 => Ok(Self::Replay),
388            8 => Ok(Self::TransactionProcessed),
389            9 => Ok(Self::TransactionIndexed),
390            10 => Ok(Self::Monitor),
391            11 => Ok(Self::ProfileIndexed),
392            12 => Ok(Self::Span),
393            13 => Ok(Self::MonitorSeat),
394            14 => Ok(Self::UserReportV2),
395            15 => Ok(Self::MetricBucket),
396            16 => Ok(Self::SpanIndexed),
397            17 => Ok(Self::ProfileDuration),
398            18 => Ok(Self::ProfileChunk),
399            19 => Ok(Self::MetricSecond),
400            20 => Ok(Self::DoNotUseReplayVideo),
401            21 => Ok(Self::Uptime),
402            22 => Ok(Self::AttachmentItem),
403            23 => Ok(Self::LogItem),
404            24 => Ok(Self::LogByte),
405            25 => Ok(Self::ProfileDurationUi),
406            26 => Ok(Self::ProfileChunkUi),
407            27 => Ok(Self::SeerAutofix),
408            28 => Ok(Self::SeerScanner),
409            29 => Ok(Self::PreventUser),
410            30 => Ok(Self::PreventReview),
411            31 => Ok(Self::SizeAnalysis),
412            32 => Ok(Self::InstallableBuild),
413            33 => Ok(Self::TraceMetric),
414            other => Err(UnknownDataCategory(other)),
415        }
416    }
417}
418
419#[cfg(test)]
420mod tests {
421    use super::*;
422
423    #[test]
424    pub fn test_last_variant_conversion() {
425        // If this test fails, update the numeric bounds so that the first assertion
426        // maps to the last variant in the enum and the second assertion produces an error
427        // that the DataCategory does not exist.
428        assert_eq!(DataCategory::try_from(33), Ok(DataCategory::TraceMetric));
429        assert_eq!(DataCategory::try_from(34), Err(UnknownDataCategory(34)));
430    }
431}
relay_base_schema/data_category.rs

relay_base_schema/
data_category.rs
