Skip to main content

relay_server/utils/
rate_limits.rs

1use std::fmt::Write;
2
3use relay_profiling::ProfileType;
4use relay_quotas::{
5    DataCategory, DimensionMap, QuotaScope, RateLimit, RateLimitScope, RateLimits, ReasonCode,
6    Scoping,
7};
8
9use crate::envelope::{AttachmentParentType, AttachmentType, Envelope, Item};
10use crate::integrations::Integration;
11
12/// Name of the rate limits header.
13pub const RATE_LIMITS_HEADER: &str = "X-Sentry-Rate-Limits";
14
15/// Formats the `X-Sentry-Rate-Limits` header.
16pub fn format_rate_limits(rate_limits: &RateLimits) -> String {
17    let mut header = String::new();
18
19    for rate_limit in rate_limits {
20        if !header.is_empty() {
21            header.push_str(", ");
22        }
23
24        write!(header, "{}:", rate_limit.retry_after.remaining_seconds()).ok();
25
26        for (index, category) in rate_limit.categories.iter().enumerate() {
27            if index > 0 {
28                header.push(';');
29            }
30            write!(header, "{category}").ok();
31        }
32
33        write!(header, ":{}", rate_limit.scope.name()).ok();
34
35        if let Some(ref reason_code) = rate_limit.reason_code {
36            write!(header, ":{reason_code}").ok();
37        } else if !rate_limit.namespaces.is_empty() {
38            write!(header, ":").ok(); // delimits the empty reason code for namespaces
39        }
40
41        for (index, namespace) in rate_limit.namespaces.iter().enumerate() {
42            header.push(if index == 0 { ':' } else { ';' });
43            write!(header, "{namespace}").ok();
44        }
45    }
46
47    header
48}
49
50/// Parses the `X-Sentry-Rate-Limits` header.
51pub fn parse_rate_limits(scoping: &Scoping, string: &str) -> RateLimits {
52    let mut rate_limits = RateLimits::new();
53
54    for limit in string.split(',') {
55        let limit = limit.trim();
56        if limit.is_empty() {
57            continue;
58        }
59
60        let mut components = limit.split(':');
61
62        let retry_after = match components.next().and_then(|s| s.parse().ok()) {
63            Some(retry_after) => retry_after,
64            None => continue,
65        };
66
67        let categories = components
68            .next()
69            .unwrap_or("")
70            .split(';')
71            .filter(|category| !category.is_empty())
72            .map(DataCategory::from_name)
73            .collect();
74
75        let quota_scope = QuotaScope::from_name(components.next().unwrap_or(""));
76        let scope = RateLimitScope::for_quota(scoping, quota_scope);
77
78        let reason_code = components
79            .next()
80            .filter(|s| !s.is_empty())
81            .map(ReasonCode::new);
82
83        let namespace = components
84            .next()
85            .unwrap_or("")
86            .split(';')
87            .filter(|s| !s.is_empty())
88            .filter_map(|s| s.parse().ok())
89            .collect();
90
91        rate_limits.add(RateLimit {
92            categories,
93            scope,
94            reason_code,
95            retry_after,
96            namespaces: namespace,
97            // The wire format cannot express dimensions, so a limit parsed from it is always
98            // a plain limit for the whole scope.
99            dimensions: DimensionMap::default(),
100        });
101    }
102
103    rate_limits
104}
105
106/// Collection of all transaction profile quantities.
107#[derive(Clone, Copy, Debug, Default)]
108pub struct ProfileQuantities {
109    /// All transaction profiles in the backend category.
110    pub backend: usize,
111    /// All transaction profiles in the ui category.
112    pub ui: usize,
113    /// All transaction profiles, includes profiles in the backend and ui categories as well as
114    /// profiles which are in neither category.
115    pub total: usize,
116}
117
118/// A summary of `Envelope` contents.
119///
120/// Aggregates header-derived quantities and relationships for early filtering, accounting and
121/// telemetry. Transaction payloads are never parsed to build this summary.
122#[non_exhaustive]
123#[derive(Clone, Copy, Debug, Default)]
124pub struct EnvelopeSummary {
125    /// The category of the first event creator, counted once per envelope.
126    pub event_category: Option<DataCategory>,
127
128    /// Total attachment storage across all parent types.
129    pub attachment_bytes: usize,
130    pub attachment_count: usize,
131
132    /// An attachment that does not create an event is present, even if already rate limited.
133    pub has_plain_attachments: bool,
134    /// Counted attachments are present for the corresponding parent type.
135    pub has_event_attachments: bool,
136    pub has_span_attachments: bool,
137    pub has_trace_attachments: bool,
138
139    /// Metrics items require client backoff even when they carry no accounting quantities.
140    pub has_metrics: bool,
141
142    /// The number of all session updates.
143    pub session_quantity: usize,
144
145    /// The number of profiles.
146    pub profile_quantity: ProfileQuantities,
147
148    /// The number of replays.
149    pub replay_quantity: usize,
150
151    /// The number of user reports (legacy item type for user feedback).
152    pub user_report_quantity: usize,
153
154    /// Whether an unrejected legacy user report participates in quota checks.
155    pub has_user_reports: bool,
156
157    /// The number of monitor check-ins.
158    pub monitor_quantity: usize,
159
160    /// The number of log for the log product sent.
161    pub log_item_quantity: usize,
162
163    /// The number of log bytes for the log product sent, in bytes
164    pub log_byte_quantity: usize,
165
166    /// Secondary number of transactions.
167    ///
168    /// This is 0 for envelopes which contain a transaction,
169    /// only secondary transaction quantity should be tracked here,
170    /// these are for example transaction counts extracted from metrics.
171    ///
172    /// A "primary" transaction is contained within the envelope,
173    /// marking the envelope data category a [`DataCategory::Transaction`].
174    pub secondary_transaction_quantity: usize,
175
176    /// See `secondary_transaction_quantity`.
177    pub secondary_span_quantity: usize,
178
179    /// Standalone spans, transaction roots and embedded spans declared in transaction headers.
180    /// Missing embedded-span counts are calculated only when a transaction is rejected.
181    pub span_quantity: usize,
182
183    /// The payload size of this envelope.
184    pub payload_size: usize,
185
186    /// The number of profile chunks in this envelope.
187    pub profile_chunk_quantity: usize,
188    /// The number of UI profile chunks in this envelope.
189    pub profile_chunk_ui_quantity: usize,
190
191    /// The number of trace metrics in this envelope.
192    pub trace_metric_quantity: usize,
193
194    /// The number of trace metric bytes in this envelope.
195    pub trace_metric_byte_quantity: usize,
196}
197
198impl EnvelopeSummary {
199    /// Creates an empty summary.
200    pub fn empty() -> Self {
201        Self::default()
202    }
203
204    /// Creates an envelope summary and aggregates the given envelope.
205    pub fn compute(envelope: &Envelope) -> Self {
206        Self::compute_items(envelope.items())
207    }
208
209    /// Summarizes the original items without parsing payloads or constructing per-item quantities.
210    pub fn compute_items<'a>(items: impl IntoIterator<Item = &'a Item>) -> Self {
211        let mut summary = Self::empty();
212
213        for item in items {
214            let data = item.data();
215            let rate_limited = data.rate_limited();
216            if !rate_limited {
217                if let Some(source) = data.source_quantities() {
218                    summary.secondary_transaction_quantity += source.transactions;
219                    summary.secondary_span_quantity += source.spans;
220                }
221                summary.payload_size += data.len();
222            }
223
224            // Event contributions and metric backoffs remain relevant even for marked items.
225            let count = if !rate_limited {
226                item.item_count().unwrap_or(1) as usize
227            } else {
228                0
229            };
230
231            match item {
232                Item::Event(_) | Item::UnrealReport(_) => {
233                    summary.event_category.get_or_insert(DataCategory::Error);
234                }
235                Item::Security(_) | Item::RawSecurity(_) => {
236                    summary.event_category.get_or_insert(DataCategory::Security);
237                }
238                Item::UserReportV2(_) => {
239                    summary
240                        .event_category
241                        .get_or_insert(DataCategory::UserReportV2);
242                }
243                Item::UserReport(_) => {
244                    summary.user_report_quantity += count;
245                    summary.has_user_reports |= !rate_limited;
246                }
247                Item::Session(_) | Item::Sessions(_) => summary.session_quantity += count,
248                Item::ReplayEvent(_) | Item::ReplayRecording(_) | Item::ReplayVideo(_) => {
249                    summary.replay_quantity += count;
250                }
251                Item::CheckIn(_) => summary.monitor_quantity += count,
252                Item::Span(_) => summary.span_quantity += count,
253                Item::MetricBuckets(_) => summary.has_metrics = true,
254                Item::FormData(_) | Item::ClientReport(_) | Item::Unknown(_) => {}
255                Item::Log(item) => {
256                    summary.log_item_quantity += count;
257                    if !rate_limited {
258                        summary.log_byte_quantity += item.data().len().max(1);
259                    }
260                }
261                Item::TraceMetric(item) => {
262                    summary.trace_metric_quantity += count;
263                    if !rate_limited {
264                        summary.trace_metric_byte_quantity += item.data().len().max(1);
265                    }
266                }
267                Item::Transaction(item) => {
268                    summary
269                        .event_category
270                        .get_or_insert(DataCategory::Transaction);
271                    if !rate_limited {
272                        summary.span_quantity += 1 + item.span_count().unwrap_or(0) as usize;
273                    }
274                }
275                Item::Profile(item) => {
276                    summary.profile_quantity.total += count;
277                    match item.profile_type() {
278                        Some(ProfileType::Backend) => summary.profile_quantity.backend += count,
279                        Some(ProfileType::Ui) => summary.profile_quantity.ui += count,
280                        None => {}
281                    }
282                }
283                Item::ProfileChunk(item) => match item.profile_type() {
284                    Some(ProfileType::Backend) => summary.profile_chunk_quantity += count,
285                    Some(ProfileType::Ui) => summary.profile_chunk_ui_quantity += count,
286                    None => {}
287                },
288                Item::Integration(item) => match item.integration_header() {
289                    Some(Integration::Errors(_)) => {
290                        summary.event_category.get_or_insert(DataCategory::Error);
291                    }
292                    Some(Integration::Spans(_)) => {
293                        summary.span_quantity += count;
294                    }
295                    Some(Integration::Logs(_)) => {
296                        summary.log_item_quantity += count;
297                        if !rate_limited {
298                            summary.log_byte_quantity += item.data().len().max(1);
299                        }
300                    }
301                    _ => {}
302                },
303                Item::Attachment(item) => {
304                    let parent = item.attachment_parent_type();
305                    // Event-parent dying messages contribute only to the event.
306                    if !rate_limited
307                        && !(item.attachment_type() == AttachmentType::NintendoSwitchDyingMessage
308                            && matches!(parent, AttachmentParentType::Event))
309                    {
310                        summary.attachment_count += 1;
311                        summary.attachment_bytes += item.attachment_body_size();
312                        match parent {
313                            AttachmentParentType::Event => summary.has_event_attachments = true,
314                            AttachmentParentType::Span => summary.has_span_attachments = true,
315                            AttachmentParentType::Trace => summary.has_trace_attachments = true,
316                        }
317                    }
318                    if item.carries_event_payload() {
319                        summary.event_category.get_or_insert(DataCategory::Error);
320                    } else {
321                        summary.has_plain_attachments = true;
322                    }
323                }
324            }
325        }
326
327        summary
328    }
329}
330
331#[cfg(test)]
332mod tests {
333    use relay_base_schema::organization::OrganizationId;
334    use relay_base_schema::project::{ProjectId, ProjectKey};
335    use relay_metrics::MetricNamespace;
336    use relay_quotas::{DimensionMap, RetryAfter};
337    use smallvec::smallvec;
338
339    use super::*;
340    use crate::envelope::MetricBucketsItem;
341    use crate::envelope::SourceQuantities;
342    use crate::extractors::RequestMeta;
343
344    #[test]
345    fn test_format_rate_limits() {
346        let mut rate_limits = RateLimits::new();
347
348        // Add a generic rate limit for all categories.
349        rate_limits.add(RateLimit {
350            categories: Default::default(),
351            scope: RateLimitScope::Organization(OrganizationId::new(42)),
352            reason_code: Some(ReasonCode::new("my_limit")),
353            retry_after: RetryAfter::from_secs(42),
354            namespaces: smallvec![],
355            dimensions: DimensionMap::default(),
356        });
357
358        // Add a more specific rate limit for just one category.
359        rate_limits.add(RateLimit {
360            categories: [DataCategory::Transaction, DataCategory::Security].into(),
361            scope: RateLimitScope::Project(ProjectId::new(21)),
362            reason_code: None,
363            retry_after: RetryAfter::from_secs(4711),
364            namespaces: smallvec![],
365            dimensions: DimensionMap::default(),
366        });
367
368        let formatted = format_rate_limits(&rate_limits);
369        let expected = "42::organization:my_limit, 4711:transaction;security:project";
370        assert_eq!(formatted, expected);
371    }
372
373    #[test]
374    fn test_format_rate_limits_namespace() {
375        let mut rate_limits = RateLimits::new();
376
377        // Rate limit with reason code and namespace.
378        rate_limits.add(RateLimit {
379            categories: [DataCategory::MetricBucket].into(),
380            scope: RateLimitScope::Organization(OrganizationId::new(42)),
381            reason_code: Some(ReasonCode::new("my_limit")),
382            retry_after: RetryAfter::from_secs(42),
383            namespaces: smallvec![MetricNamespace::Transactions, MetricNamespace::Spans],
384            dimensions: DimensionMap::default(),
385        });
386
387        // Rate limit without reason code.
388        rate_limits.add(RateLimit {
389            categories: [DataCategory::MetricBucket].into(),
390            scope: RateLimitScope::Organization(OrganizationId::new(42)),
391            reason_code: None,
392            retry_after: RetryAfter::from_secs(42),
393            namespaces: smallvec![MetricNamespace::Spans],
394            dimensions: DimensionMap::default(),
395        });
396
397        let formatted = format_rate_limits(&rate_limits);
398        let expected = "42:metric_bucket:organization:my_limit:transactions;spans, 42:metric_bucket:organization::spans";
399        assert_eq!(formatted, expected);
400    }
401
402    #[test]
403    fn test_parse_invalid_rate_limits() {
404        let scoping = Scoping {
405            organization_id: OrganizationId::new(42),
406            project_id: ProjectId::new(21),
407            project_key: ProjectKey::parse("a94ae32be2584e0bbd7a4cbb95971fee").unwrap(),
408            key_id: Some(17),
409        };
410
411        assert!(parse_rate_limits(&scoping, "").is_ok());
412        assert!(parse_rate_limits(&scoping, "invalid").is_ok());
413        assert!(parse_rate_limits(&scoping, ",,,").is_ok());
414    }
415
416    #[test]
417    fn test_parse_rate_limits() {
418        let scoping = Scoping {
419            organization_id: OrganizationId::new(42),
420            project_id: ProjectId::new(21),
421            project_key: ProjectKey::parse("a94ae32be2584e0bbd7a4cbb95971fee").unwrap(),
422            key_id: Some(17),
423        };
424
425        // contains "foobar", an unknown scope that should be mapped to Unknown
426        let formatted =
427            "42::organization:my_limit, invalid, 4711:foobar;transaction;security:project";
428        let rate_limits: Vec<RateLimit> =
429            parse_rate_limits(&scoping, formatted).into_iter().collect();
430
431        assert_eq!(
432            rate_limits,
433            vec![
434                RateLimit {
435                    categories: Default::default(),
436                    scope: RateLimitScope::Organization(OrganizationId::new(42)),
437                    reason_code: Some(ReasonCode::new("my_limit")),
438                    retry_after: rate_limits[0].retry_after,
439                    namespaces: smallvec![],
440                    dimensions: DimensionMap::default(),
441                },
442                RateLimit {
443                    categories: [
444                        DataCategory::Unknown,
445                        DataCategory::Transaction,
446                        DataCategory::Security,
447                    ]
448                    .into(),
449                    scope: RateLimitScope::Project(ProjectId::new(21)),
450                    reason_code: None,
451                    retry_after: rate_limits[1].retry_after,
452                    namespaces: smallvec![],
453                    dimensions: DimensionMap::default(),
454                }
455            ]
456        );
457
458        assert_eq!(42, rate_limits[0].retry_after.remaining_seconds());
459        assert_eq!(4711, rate_limits[1].retry_after.remaining_seconds());
460    }
461
462    #[test]
463    fn test_parse_rate_limits_namespace() {
464        let scoping = Scoping {
465            organization_id: OrganizationId::new(42),
466            project_id: ProjectId::new(21),
467            project_key: ProjectKey::parse("a94ae32be2584e0bbd7a4cbb95971fee").unwrap(),
468            key_id: Some(17),
469        };
470
471        let formatted = "42:metric_bucket:organization::transactions;spans";
472        let rate_limits: Vec<RateLimit> =
473            parse_rate_limits(&scoping, formatted).into_iter().collect();
474
475        assert_eq!(
476            rate_limits,
477            vec![RateLimit {
478                categories: [DataCategory::MetricBucket].into(),
479                scope: RateLimitScope::Organization(OrganizationId::new(42)),
480                reason_code: None,
481                retry_after: rate_limits[0].retry_after,
482                namespaces: smallvec![MetricNamespace::Transactions, MetricNamespace::Spans],
483                dimensions: DimensionMap::default(),
484            }]
485        );
486    }
487
488    #[test]
489    fn test_parse_rate_limits_empty_namespace() {
490        let scoping = Scoping {
491            organization_id: OrganizationId::new(42),
492            project_id: ProjectId::new(21),
493            project_key: ProjectKey::parse("a94ae32be2584e0bbd7a4cbb95971fee").unwrap(),
494            key_id: Some(17),
495        };
496
497        // notice the trailing colon
498        let formatted = "42:metric_bucket:organization:some_reason:";
499        let rate_limits: Vec<RateLimit> =
500            parse_rate_limits(&scoping, formatted).into_iter().collect();
501
502        assert_eq!(
503            rate_limits,
504            vec![RateLimit {
505                categories: [DataCategory::MetricBucket].into(),
506                scope: RateLimitScope::Organization(OrganizationId::new(42)),
507                reason_code: Some(ReasonCode::new("some_reason")),
508                retry_after: rate_limits[0].retry_after,
509                namespaces: smallvec![],
510                dimensions: DimensionMap::default(),
511            }]
512        );
513    }
514
515    #[test]
516    fn test_parse_rate_limits_only_unknown() {
517        let scoping = Scoping {
518            organization_id: OrganizationId::new(42),
519            project_id: ProjectId::new(21),
520            project_key: ProjectKey::parse("a94ae32be2584e0bbd7a4cbb95971fee").unwrap(),
521            key_id: Some(17),
522        };
523
524        let formatted = "42:foo;bar:organization";
525        let rate_limits: Vec<RateLimit> =
526            parse_rate_limits(&scoping, formatted).into_iter().collect();
527
528        assert_eq!(
529            rate_limits,
530            vec![RateLimit {
531                categories: [DataCategory::Unknown, DataCategory::Unknown].into(),
532                scope: RateLimitScope::Organization(OrganizationId::new(42)),
533                reason_code: None,
534                retry_after: rate_limits[0].retry_after,
535                namespaces: smallvec![],
536                dimensions: DimensionMap::default(),
537            },]
538        );
539    }
540    #[test]
541    fn test_source_quantity_for_total_quantity() {
542        let dsn = "https://e12d836b15bb49d7bbf99e64295d995b:@sentry.io/42"
543            .parse()
544            .unwrap();
545        let request_meta = RequestMeta::new(dsn);
546
547        let mut envelope = Envelope::from_request(None, request_meta);
548
549        let mut item = MetricBucketsItem::new();
550        item.data_mut().set_source_quantities(SourceQuantities {
551            transactions: 5,
552            spans: 0,
553            buckets: 5,
554        });
555        envelope.add_item(item);
556
557        let mut item = MetricBucketsItem::new();
558        item.data_mut().set_source_quantities(SourceQuantities {
559            transactions: 2,
560            spans: 0,
561            buckets: 3,
562        });
563        envelope.add_item(item);
564
565        let summary = EnvelopeSummary::compute(&envelope);
566
567        assert_eq!(summary.secondary_transaction_quantity, 7);
568    }
569}