Skip to main content

relay_profiling/
lib.rs

1//! Profiling protocol and processing for Sentry.
2//!
3//! Profiles are captured during the life of a transaction on Sentry clients and sent to Relay for
4//! ingestion as JSON objects with some metadata. They are sent alongside a transaction (usually in
5//! the same envelope) and are usually big objects (average size around 300KB and it's not unusual
6//! to see several MB). Their size is linked to the amount of code executed during the transaction
7//! (so the duration of the transaction influences the size of the profile).
8//!
9//! It's preferrable to have a profile with a transaction. If a transaction is dropped, the profile
10//! should be dropped as well.
11//!
12//! # Envelope
13//!
14//! ## Transaction Profiling
15//!
16//! To send a profile of a transaction to Relay, the profile is enclosed in an item of type
17//! `profile`:
18//! ```json
19//! {"type": "profile", "size": ...}
20//! { ... }
21//! ```
22//! ## Continuous Profiling
23//!
24//! For continuous profiling, we expect to receive chunks of profile in an item of type
25//! `profile_chunk`:
26//! ```json
27//! {"type": "profile_chunk"}
28//! { ... }
29//! ```
30//!
31//! # Protocol
32//!
33//! Each item type expects a different format.
34//!
35//! For `Profile` item type, we expect the Sample format v1 or Android format.
36//! For `ProfileChunk` item type, we expect the Sample format v2 or Android trace chunk format.
37//!
38//! # Ingestion
39//!
40//! Relay will forward those profiles encoded with `msgpack` after unpacking them if needed and push a message on Kafka.
41
42use std::error::Error;
43use std::net::IpAddr;
44use std::time::Duration;
45
46use relay_dynamic_config::GlobalConfig;
47use relay_event_schema::protocol::{Event, EventId};
48use relay_filter::ProjectFiltersConfig;
49use serde_json::Deserializer;
50
51use crate::extract_from_transaction::{extract_transaction_metadata, extract_transaction_tags};
52
53pub use crate::error::ProfileError;
54pub use crate::outcomes::discard_reason;
55
56mod android;
57mod debug_image;
58mod error;
59mod extract_from_transaction;
60pub mod flamegraph;
61mod measurements;
62mod outcomes;
63mod perfetto;
64mod profile_chunk;
65mod sample;
66mod transaction_metadata;
67mod types;
68mod utils;
69
70pub use self::android::chunk::Chunk as AndroidProfileChunk;
71pub use self::perfetto::Chunk as PerfettoProfileChunk;
72pub use self::profile_chunk::{AndroidOrV2ProfileChunk, AnyProfileChunk, ProfileChunk};
73pub use self::sample::v2::ProfileChunk as V2ProfileChunk;
74
75const MAX_PROFILE_DURATION: Duration = Duration::from_secs(30);
76/// For continuous profiles, each chunk can be at most 1 minute.
77/// In certain circumstances (e.g. high cpu load) the profiler
78/// the profiler may be stopped slightly after 60, hence here we
79/// give it a bit more room to handle such cases (66 instead of 60)
80const MAX_PROFILE_CHUNK_DURATION: Duration = Duration::from_secs(66);
81
82/// Prefix used in [`relay_protocol::Getter`] implementations as a prefix.
83///
84/// This is `event.` for historic reasons, we should consider switching this to `profile.`.
85const PROFIL_GETTER_PREFIX: &str = "event.";
86
87/// Unique identifier for a profile.
88///
89/// Same format as event IDs.
90pub type ProfileId = EventId;
91
92/// Determines the type/use of a [`ProfileChunk`].
93#[derive(Debug, Clone, Copy, PartialEq, Eq)]
94pub enum ProfileType {
95    /// A backend profile.
96    Backend,
97    /// A UI profile.
98    Ui,
99}
100
101impl ProfileType {
102    /// Converts a platform to a [`ProfileType`].
103    ///
104    /// The profile type is currently determined based on the contained profile
105    /// platform. It determines the data category this profile chunk belongs to.
106    ///
107    /// This needs to be synchronized with the implementation in Sentry:
108    /// <https://github.com/getsentry/sentry/blob/ed2e1c8bcd0d633e6f828fcfbeefbbdd98ef3dba/src/sentry/profiles/task.py#L995>
109    pub fn from_platform(platform: &str) -> Self {
110        match platform {
111            "cocoa" | "android" | "javascript" => Self::Ui,
112            _ => Self::Backend,
113        }
114    }
115}
116
117#[derive(Debug, serde::Deserialize)]
118struct MinimalProfile {
119    #[serde(alias = "profile_id", alias = "chunk_id")]
120    event_id: ProfileId,
121    platform: String,
122    release: Option<String>,
123    #[serde(default)]
124    version: sample::Version,
125}
126
127impl MinimalProfile {
128    fn parse(payload: &[u8]) -> Result<Self, serde_path_to_error::Error<serde_json::Error>> {
129        let d = &mut serde_json::Deserializer::from_slice(payload);
130        serde_path_to_error::deserialize(d)
131    }
132}
133
134impl relay_filter::Filterable for MinimalProfile {
135    fn release(&self) -> Option<&str> {
136        self.release.as_deref()
137    }
138}
139
140impl relay_protocol::Getter for MinimalProfile {
141    fn get_value(&self, path: &str) -> Option<relay_protocol::Val<'_>> {
142        match path.strip_prefix("event.")? {
143            "release" => self.release.as_deref().map(|release| release.into()),
144            "platform" => Some(self.platform.as_str().into()),
145            _ => None,
146        }
147    }
148}
149
150/// Parsed profile metadata returned from [`parse_metadata`].
151#[derive(Debug)]
152pub struct ProfileMetadata {
153    pub id: ProfileId,
154    pub platform: String,
155}
156
157impl ProfileMetadata {
158    /// Returns the [`ProfileType`] of the profile.
159    ///
160    /// The [`ProfileType`] is inferred from the platform.
161    pub fn profile_type(&self) -> ProfileType {
162        ProfileType::from_platform(&self.platform)
163    }
164}
165
166pub fn parse_metadata(payload: &[u8]) -> Result<ProfileMetadata, ProfileError> {
167    let profile = match MinimalProfile::parse(payload) {
168        Ok(profile) => profile,
169        Err(err) => {
170            relay_log::debug!(
171                error = &err as &dyn Error,
172                from = "minimal",
173                "invalid profile"
174            );
175            return Err(ProfileError::InvalidJson(err));
176        }
177    };
178    match profile.version {
179        sample::Version::V1 => {
180            let d = &mut Deserializer::from_slice(payload);
181            let _: sample::v1::ProfileMetadata = match serde_path_to_error::deserialize(d) {
182                Ok(profile) => profile,
183                Err(err) => {
184                    relay_log::debug!(
185                        error = &err as &dyn Error,
186                        from = "metadata",
187                        platform = profile.platform,
188                        "invalid profile",
189                    );
190                    return Err(ProfileError::InvalidJson(err));
191                }
192            };
193        }
194        _ => match profile.platform.as_str() {
195            "android" => {
196                let d = &mut Deserializer::from_slice(payload);
197                let _: android::legacy::ProfileMetadata = match serde_path_to_error::deserialize(d)
198                {
199                    Ok(profile) => profile,
200                    Err(err) => {
201                        relay_log::debug!(
202                            error = &err as &dyn Error,
203                            from = "metadata",
204                            platform = "android",
205                            "invalid profile",
206                        );
207                        return Err(ProfileError::InvalidJson(err));
208                    }
209                };
210            }
211            _ => return Err(ProfileError::PlatformNotSupported),
212        },
213    };
214
215    Ok(ProfileMetadata {
216        id: profile.event_id,
217        platform: profile.platform,
218    })
219}
220
221pub fn expand_profile(
222    payload: &[u8],
223    event: &Event,
224    client_ip: Option<IpAddr>,
225    filter_settings: &ProjectFiltersConfig,
226    global_config: &GlobalConfig,
227) -> Result<(ProfileId, Vec<u8>), ProfileError> {
228    let profile = match MinimalProfile::parse(payload) {
229        Ok(profile) => profile,
230        Err(err) => {
231            relay_log::debug!(
232                error = &err as &dyn Error,
233                from = "minimal",
234                platform = event.platform.as_str(),
235                project_id = event.project.value().unwrap_or(&0),
236                sdk_name = event.sdk_name(),
237                sdk_version = event.sdk_version(),
238                transaction_id = ?event.id.value(),
239                "invalid profile",
240            );
241            return Err(ProfileError::InvalidJson(err));
242        }
243    };
244
245    if let Err(filter_stat_key) = relay_filter::should_filter(
246        &profile,
247        client_ip,
248        filter_settings,
249        global_config.filters(),
250    ) {
251        return Err(ProfileError::Filtered(filter_stat_key));
252    }
253
254    let transaction_metadata = extract_transaction_metadata(event);
255    let transaction_tags = extract_transaction_tags(event);
256    let processed_payload = match (profile.platform.as_str(), profile.version) {
257        (_, sample::Version::V1) => {
258            sample::v1::parse_sample_profile(payload, transaction_metadata, transaction_tags)
259        }
260        ("android", _) => {
261            android::legacy::parse_android_profile(payload, transaction_metadata, transaction_tags)
262        }
263        (_, _) => return Err(ProfileError::PlatformNotSupported),
264    };
265    match processed_payload {
266        Ok(payload) => Ok((profile.event_id, payload)),
267        Err(err) => match err {
268            ProfileError::InvalidJson(err) => {
269                relay_log::debug!(
270                    error = &err as &dyn Error,
271                    from = "parsing",
272                    platform = profile.platform,
273                    project_id = event.project.value().unwrap_or(&0),
274                    sdk_name = event.sdk_name(),
275                    sdk_version = event.sdk_version(),
276                    transaction_id = ?event.id.value(),
277                    "invalid profile",
278                );
279                Err(ProfileError::InvalidJson(err))
280            }
281            _ => {
282                relay_log::debug!(
283                    error = &err as &dyn Error,
284                    from = "parsing",
285                    platform = profile.platform,
286                    project_id = event.project.value().unwrap_or(&0),
287                    sdk_name = event.sdk_name(),
288                    sdk_version = event.sdk_version(),
289                    transaction_id = ?event.id.value(),
290                    "invalid profile",
291                );
292                Err(err)
293            }
294        },
295    }
296}
297
298#[cfg(test)]
299mod tests {
300    use super::*;
301
302    #[test]
303    fn test_minimal_profile_with_version() {
304        let data = r#"{"version":"1","platform":"cocoa","event_id":"751fff80-a266-467b-a6f5-eeeef65f4f84"}"#;
305        let profile = MinimalProfile::parse(data.as_bytes());
306        assert!(profile.is_ok());
307        assert_eq!(profile.unwrap().version, sample::Version::V1);
308    }
309
310    #[test]
311    fn test_minimal_profile_without_version() {
312        let data = r#"{"platform":"android","event_id":"751fff80-a266-467b-a6f5-eeeef65f4f84"}"#;
313        let profile = MinimalProfile::parse(data.as_bytes());
314        assert!(profile.is_ok());
315        assert_eq!(profile.unwrap().version, sample::Version::Unknown);
316    }
317
318    #[test]
319    fn test_expand_profile_with_version() {
320        let payload = include_bytes!("../tests/fixtures/sample/v1/valid.json");
321        assert!(
322            expand_profile(
323                payload,
324                &Event::default(),
325                None,
326                &ProjectFiltersConfig::default(),
327                &GlobalConfig::default()
328            )
329            .is_ok()
330        );
331    }
332
333    #[test]
334    fn test_expand_profile_with_version_and_segment_id() {
335        let payload = include_bytes!("../tests/fixtures/sample/v1/segment_id.json");
336        assert!(
337            expand_profile(
338                payload,
339                &Event::default(),
340                None,
341                &ProjectFiltersConfig::default(),
342                &GlobalConfig::default()
343            )
344            .is_ok()
345        );
346    }
347
348    #[test]
349    fn test_expand_profile_without_version() {
350        let payload = include_bytes!("../tests/fixtures/android/legacy/roundtrip.json");
351        assert!(
352            expand_profile(
353                payload,
354                &Event::default(),
355                None,
356                &ProjectFiltersConfig::default(),
357                &GlobalConfig::default()
358            )
359            .is_ok()
360        );
361    }
362}