From a6e00a2f5633e66976dfe47ad200b2276c871fad Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Fri, 28 Nov 2025 13:58:28 -0500 Subject: [PATCH 1/2] feat: Update ui profiling electron docs --- .../explore/logs/getting-started/index.mdx | 5 ++ ...ontinuous-ui-profiling-migration-guide.mdx | 56 ++++++++++++++----- .../browser-profiling/javascript.mdx | 22 ++++---- 3 files changed, 57 insertions(+), 26 deletions(-) diff --git a/docs/product/explore/logs/getting-started/index.mdx b/docs/product/explore/logs/getting-started/index.mdx index f453711098d0e1..3ca8d184fb0a54 100644 --- a/docs/product/explore/logs/getting-started/index.mdx +++ b/docs/product/explore/logs/getting-started/index.mdx @@ -302,6 +302,11 @@ To set up Sentry Logs, use the links below for supported SDKs. After it's been s label="Unreal Engine" url="/platforms/unreal/logs/" /> +- ## Upcoming SDKs diff --git a/docs/product/explore/profiling/continuous-ui-profiling-migration-guide.mdx b/docs/product/explore/profiling/continuous-ui-profiling-migration-guide.mdx index a105411e10190b..cb059ab6ae7df7 100644 --- a/docs/product/explore/profiling/continuous-ui-profiling-migration-guide.mdx +++ b/docs/product/explore/profiling/continuous-ui-profiling-migration-guide.mdx @@ -17,42 +17,68 @@ For the remainder of this document, you can assume that wherever “Continuous/U Continuous Profiling is supported on the following SDKs: -- [Python](/platforms/python/profiling/) `2.24.1` -- [Node.js](/platforms/javascript/guides/node/profiling/) `9.8.0` +- +- UI Profiling is supported on the following SDKs: -- [iOS & macOS](/platforms/apple/profiling/) `8.49.0` -- [Android (Java & Kotlin only)](/platforms/android/profiling/) `8.5.0` +- +- +- +- If you are using any other SDKs that currently support transaction-based profiling, those SDKs do not yet support Continuous or UI Profiling. We will be adding support for more SDKs over time. ## Identifying Current API Usage -If you are specifying either the `profiles_sample_rate` or `profiles_sampler` configuration options, you are using transaction-based profiling. +If you are specifying either the `profiles_sample_rate` or `profiles_sampler` configuration options, you are using transaction-based profiling. -If you are specifying the `profile_session_sample_rate` and/or `profile_lifecycle` configuration options, you are using Continuous Profiling or UI Profiling. +If you are specifying the `profile_session_sample_rate` and/or `profile_lifecycle` configuration options, you are using Continuous Profiling or UI Profiling. ## Migrating to Continuous/UI Profiling ### 1. Replace the `profiles_sample_rate` and `profiles_sampler` SDK configuration options with `profile_session_sample_rate` -There is an important distinction in how client-side sampling is implemented between transaction-based and Continuous/UI Profiling. `profiles_sample_rate` and `profiles_sampler` were used to evaluate whether the profile would be sampled *for each transaction*. In other words, if `profiles_sample_rate` was set to 0.5, 50% of all transactions would have associated profiles. `profiles_sampler` worked similarly — the only difference was that you could implement custom sampling logic (rather than a fixed sample rate) based on the context of the transaction being sampled. +There is an important distinction in how client-side sampling is implemented between transaction-based and Continuous/UI Profiling. `profiles_sample_rate` and `profiles_sampler` were used to evaluate whether the profile would be sampled _for each transaction_. In other words, if `profiles_sample_rate` was set to 0.5, 50% of all transactions would have associated profiles. `profiles_sampler` worked similarly — the only difference was that you could implement custom sampling logic (rather than a fixed sample rate) based on the context of the transaction being sampled. -In contrast, Continuous/UI Profiling use client-side sampling that is *session scoped,* configured via the new `profile_session_sample_rate` parameter. Sampling is evaluated once at the beginning of each session, not every time profiling data is collected. Since the scope at which sampling is applied is different, you can’t just directly translate the previous `profiles_sample_rate` value to `profile_session_sample_rate`. +In contrast, Continuous/UI Profiling use client-side sampling that is _session scoped,_ configured via the new `profile_session_sample_rate` parameter. Sampling is evaluated once at the beginning of each session, not every time profiling data is collected. Since the scope at which sampling is applied is different, you can’t just directly translate the previous `profiles_sample_rate` value to `profile_session_sample_rate`. To control client side sampling behavior, set the `profile_session_sample_rate` configuration parameter to a value from 0.0-1.0 (default is 0.0) to control the number of profiling sessions that are sampled. The way this sampling rate is applied depends on the context: - **For Continuous Profiling**: the session starts when the Sentry SDK is initialized, and stops when the service or process is terminated. Sampling is only evaluated once during the process lifetime (during initialization.) - - For example, if you are using Continuous Profiling with a backend service where there are N instances of the same service that are deployed (such as N containers, pods, etc.), the `profile_session_sample_rate` controls the percentage of those instances that will have profiling enabled. 0.5 would mean that a randomly sampled 50% of the N instances would have profiling enabled. - - Sampling would only be re-evaluated once an instance restarts or is re-deployed -- **For UI Profiling:** the initial user session starts when the Sentry SDK is initialized, and sampling is first evaluated at this point. The user session will either end on termination of the application *OR*, depending on the platform, there can be other events that end a user session (for example backgrounding a mobile application). The sampling rate will be re-evaluated on each new user session. - - For example, on the browser, the user session begins when the tab is opened and ends when the tab is closed. The sampling will be evaluated once at the start of each session, so if `profile_session_sample_rate` is set to 0.5, then 50% of the time your application is opened in a tab, profiling will be active for that tab’s lifetime. - - On mobile, the user session begins when the application is started or foregrounded, and ends when the application is terminated or backgrounded. The sampling will be evaluated once at the start of each session, so if `profile_session_sample_rate` is set to 0.5 then 50% of the time the user opens your mobile app, profiling will be active until the user backgrounds or quits the app. - + - For example, if you are using Continuous Profiling with a backend service where there are N instances of the same service that are deployed (such as N containers, pods, etc.), the `profile_session_sample_rate` controls the percentage of those instances that will have profiling enabled. 0.5 would mean that a randomly sampled 50% of the N instances would have profiling enabled. + - Sampling would only be re-evaluated once an instance restarts or is re-deployed +- **For UI Profiling:** the initial user session starts when the Sentry SDK is initialized, and sampling is first evaluated at this point. The user session will either end on termination of the application _OR_, depending on the platform, there can be other events that end a user session (for example backgrounding a mobile application). The sampling rate will be re-evaluated on each new user session. + - For example, on the browser, the user session begins when the tab is opened and ends when the tab is closed. The sampling will be evaluated once at the start of each session, so if `profile_session_sample_rate` is set to 0.5, then 50% of the time your application is opened in a tab, profiling will be active for that tab’s lifetime. + - On mobile, the user session begins when the application is started or foregrounded, and ends when the application is terminated or backgrounded. The sampling will be evaluated once at the start of each session, so if `profile_session_sample_rate` is set to 0.5 then 50% of the time the user opens your mobile app, profiling will be active until the user backgrounds or quits the app. + ### 2. Set the new `profile_lifecycle` SDK configuration option -Continuous/UI Profiling support two lifecycle modes: `manual` and `trace`. +Continuous/UI Profiling support two lifecycle modes: `manual` and `trace`. **`manual` is the default mode** and allows you to more directly control when the profiler is running by calling the `start_profile_session` and `stop_profile_session` functions. If you decide to use this mode, you must add these start/stop calls anywhere in your code that you want profiling to be active. If `start_profile_session` is not called, profiling will never occur. Note that this respects `profile_session_sample_rate` — if the session is not sampled, no profiling data will be collected even if `start_profile_session` is called. diff --git a/platform-includes/profiling/browser-profiling/javascript.mdx b/platform-includes/profiling/browser-profiling/javascript.mdx index cf860b9adbcf2b..8a9ccc6faa4ea9 100644 --- a/platform-includes/profiling/browser-profiling/javascript.mdx +++ b/platform-includes/profiling/browser-profiling/javascript.mdx @@ -14,24 +14,25 @@ Note that since the profiling API is currently only exposed in Chromium, profile To get started with JavaScript browser profiling, you'll need to: -- Install the SDK, minimum version `10.27.0` (UI Profiling) or `7.60.0` (deprecated transaction-based Profiling) -- Configure the document response header to include `Document-Policy: js-profiling` -- Configure the SDK to use the `browserProfilingIntegration` and set `profileSessionSampleRate` (UI Profiling) or `profilesSampleRate` (deprecated transaction-based Profiling) - -## Step 1: Install the SDK - -Install our SDK using either `yarn` or `npm`, the minimum version that supports profiling is **7.60.0**. +- Install the SDK, minimum version `10.27.0` (UI Profiling) or `7.60.0` (deprecated transaction-based Profiling) -Install our Electron SDK using either `yarn` or `npm`, the minimum version that supports profiling is **4.16.0**. +- Install the SDK, minimum version `4.16.0` (UI Profiling) or `7.4.0` (deprecated transaction-based Profiling) +- Configure the document response header to include `Document-Policy: js-profiling` +- Configure the SDK to use the `browserProfilingIntegration` and set `profileSessionSampleRate` (UI Profiling) or `profilesSampleRate` (deprecated transaction-based Profiling) + +## Step 1: Install the SDK + +Install our SDK using either `npm`, `yarn`, or `pnpm`. + ## Step 2: Add Document-Policy: js-profiling header @@ -60,7 +61,6 @@ In `manual` mode, you can manage the profiling data collection via calls to `Sen In `trace` mode, the profiler manages its own start and stop calls based on spans. It continues to run while at least one span is active, and stops when there are no active spans. - ### Manual Lifecycle Profiling Manual lifecycle profiling is the default mode and enables you to start and stop the profiler manually. @@ -83,11 +83,11 @@ Sentry.init({ dsn: "___PUBLIC_DSN___", integrations: [ Sentry.browserTracingIntegration(), // Enables tracing - Sentry.browserProfilingIntegration() + Sentry.browserProfilingIntegration(), ], tracesSampleRate: 1.0, // Enables tracing profileSessionSampleRate: 1.0, - profileLifecycle: 'trace', + profileLifecycle: "trace", }); ``` From fca0641ea9fb800d10421a074e7ca16c3486c379 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Fri, 28 Nov 2025 14:10:37 -0500 Subject: [PATCH 2/2] Apply suggestion from @AbhiPrasad --- platform-includes/profiling/browser-profiling/javascript.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/profiling/browser-profiling/javascript.mdx b/platform-includes/profiling/browser-profiling/javascript.mdx index 8a9ccc6faa4ea9..89ff6dde5c7e1e 100644 --- a/platform-includes/profiling/browser-profiling/javascript.mdx +++ b/platform-includes/profiling/browser-profiling/javascript.mdx @@ -22,7 +22,7 @@ To get started with JavaScript browser profiling, you'll need to: -- Install the SDK, minimum version `4.16.0` (UI Profiling) or `7.4.0` (deprecated transaction-based Profiling) +- Install the SDK, minimum version `7.4.0` (UI Profiling) or `4.16.0` (deprecated transaction-based Profiling)