docs(profiling): Add docs for UI profiling (Browser JS) (#15611)

s1gr1d · philipphofmann · commit 95b77219d1be · 2025-11-28T08:40:04.000+01:00
## DESCRIBE YOUR PR Adds docs for the new UI Profiling APIs in the browser. part of getsentry/sentry-javascript#17279 ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.):  - [ ] Other deadline:  - [ ] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs)
diff --git a/develop-docs/sdk/telemetry/profiles/continuous-profiling-api.mdx b/develop-docs/sdk/telemetry/profiles/continuous-profiling-api.mdx
@@ -74,7 +74,7 @@ Those are the two modes:
 - **`'trace'`**:  **This mode requires tracing to be enabled.** The profiler starts automatically when there is at least one active root span and stops when there are no active root spans (letting the current chunk completely finish).
   - Profiling respects **both** `profile_session_sample_rate` and the tracing sampling configuration (`traces_sample_rate` or `traces_sampler`).
   - `profile_session_sample_rate` is checked first. If the session is not sampled, no profiling will occur.
-  - If the session is sampled, `traces_sample_rate` / `traces_sampler` is evaluated for each root span to determine if it should be profiled.
+  - Only if a root span is sampled (this is based on `traces_sample_rate` / `traces_sampler`), profiling will start. Therefore, profile sampling is re-evaluated for each root span.
   - The profiler runs as long as there is at least one **sampled** root span. If multiple root spans overlap, profiling continues until the last sampled root span finishes.
 
 <Alert level="warning">
diff --git a/docs/platforms/android/profiling/index.mdx b/docs/platforms/android/profiling/index.mdx
@@ -19,7 +19,7 @@ The transaction-based profiler is available on SDK versions `6.16.0` and higher
 
 ## Enabling UI Profiling
 
-UI Profiling supports two modes - `manual` and `trace`. The two modes are mutually exclusive, and cannot be used at the same time.
+UI Profiling supports two modes: `manual` and `trace`. These modes are mutually exclusive and cannot be used at the same time.
 
 In `manual` mode, the profiling data collection can be managed via calls to `Sentry.profiler.startProfiler` and `Sentry.profiler.stopProfiler`. You are entirely in the in control of when the profiler runs.
 
diff --git a/docs/platforms/java/common/profiling/index.mdx b/docs/platforms/java/common/profiling/index.mdx
@@ -37,7 +37,7 @@ implementation 'io.sentry:sentry-async-profiler:{{@inject packages.version('sent
 
 ## Enabling Continuous Profiling
 
-Continuous profiling supports two modes - `manual` and `trace`. The two modes are mutually exclusive, and cannot be used at the same time.
+Continuous Profiling supports two modes: `manual` and `trace`. These modes are mutually exclusive and cannot be used at the same time.
 
 In `manual` mode, the profiling data collection can be managed via calls to `Sentry.startProfiler()` and `Sentry.stopProfiler()`. You are entirely in control of when the profiler runs.
 
@@ -61,5 +61,5 @@ Continuous profiling for Java is currently supported on:
 - macOS
 - Linux
 
-The profiler uses [async-profiler](https://github.com/async-profiler/async-profiler) under the hood to collect profiling data. 
+The profiler uses [async-profiler](https://github.com/async-profiler/async-profiler) under the hood to collect profiling data.
 
diff --git a/docs/platforms/javascript/common/configuration/options.mdx b/docs/platforms/javascript/common/configuration/options.mdx
@@ -548,12 +548,41 @@ The sample rate for replays that are recorded when an error happens. This type o
 
 ## Profiling Options
 
+<SdkOption name="profileSessionSampleRate" type='number' availableSince="10.27.0">
+
+  A number between `0` and `1` that sets the percentage of how many sessions should have profiling enabled. `1.0` enables profiling in every session, `0.5` enables profiling for 50% of the sessions, and `0` enables it for none. The sampling decision is made once at the beginning of a session. This option is required to enable profiling.
+
+  <PlatformCategorySection categorySupported={["server", "serverless"]}>
+    In a server environment, a profiling session starts when the Sentry SDK is initialized and stops when the service terminates.
+    Therefore, the sampling decision is re-evaluated on service restart or redeployment.
+  </PlatformCategorySection>
+
+  <PlatformCategorySection supported={['browser']}>
+    In a browser environment, a profiling session corresponds to a user session. A user session starts with a
+    new SDK initialization on page load and ends when the browser tab is closed.
+  </PlatformCategorySection>
+</SdkOption>
+
+
+<SdkOption name="profileLifecycle" type='"trace" | "manual"' defaultValue='"manual"' availableSince="10.27.0">
+
+Determines how profiling sessions are controlled. It has two modes:
+
+- `'manual'` (default): You control when profiling starts and stops using the `startProfiler()` and `stopProfiler()` functions. In this mode, profile sampling is only affected by `profileSessionSampleRate`. Read more about these functions in the <PlatformLink to="/profiling">profiling API documentation</PlatformLink>.
+- `'trace'`: Profiling starts and stops automatically with transactions, as long as tracing is enabled. The profiler runs as long as there is at least one sampled transaction. In this mode, profiling is affected by both `profileSessionSampleRate` and your tracing sample rate (`tracesSampleRate` or `tracesSampler`).
+
+</SdkOption>
+
+
 <SdkOption name="profilesSampleRate" type='number'>
 
-A number between `0` and `1`, controlling the percentage chance a given sampled transaction will be profiled. (`0` represents 0% while `1` represents 100%.) Applies equally to all transactions created in the app. This is relative to the tracing sample rate - e.g. `0.5` means 50% of sampled transactions will be profiled.
+  **Deprecated:** Use `profileSessionSampleRate` instead to configure continuous profiling from version 10.27.0 onwards.
+
+  A number between `0` and `1`, controlling the percentage chance a given sampled transaction will be profiled. (`0` represents 0% while `1` represents 100%.) Applies equally to all transactions created in the app. This is relative to the tracing sample rate - e.g. `0.5` means 50% of sampled transactions will be profiled.
 
 </SdkOption>
 
+
 <PlatformSection supported={["javascript.cordova", "javascript.capacitor"]}>
 
 ## Experimental Options
diff --git a/docs/platforms/javascript/guides/astro/index.mdx b/docs/platforms/javascript/guides/astro/index.mdx
@@ -187,9 +187,8 @@ Sentry.init({
   // ___PRODUCT_OPTION_END___ performance
   // ___PRODUCT_OPTION_START___ profiling
 
-  // Set sampling rate for profiling
-  // This is relative to tracesSampleRate
-  profilesSampleRate: 1.0,
+  // Define how many user sessions have profiling enabled.
+  profileSessionSampleRate: 1.0,
   // ___PRODUCT_OPTION_END___ profiling
 });
 ```
diff --git a/docs/platforms/python/profiling/index.mdx b/docs/platforms/python/profiling/index.mdx
@@ -20,7 +20,7 @@ Continuous profiling is available starting in SDK version `2.24.1`.
 
 </Alert>
 
-Continuous profiling supports two modes - `manual` and `trace`. The two modes are mutually exclusive, and cannot be used at the same time.
+Continuous Profiling supports two modes: `manual` and `trace`. These modes are mutually exclusive and cannot be used at the same time.
 
 In `manual` mode, the profiling data collection can be managed via calls to `sentry_sdk.profiler.start_profiler` and `sentry_sdk.profiler.stop_profiler`. You are entirely in control of when the profiler runs.
 
diff --git a/docs/product/explore/profiling/getting-started.mdx b/docs/product/explore/profiling/getting-started.mdx
@@ -4,7 +4,7 @@ sidebar_order: 2
 description: "Get started with Profiling, which allows you to see code-level profiling information for your Sentry apps."
 ---
 
-Continuous Profiling and UI Profiling are the latest iteration of Sentry’s profiling capabilities, but they are currently only supported in select SDKs as described below. 
+Continuous Profiling and UI Profiling are the latest iteration of Sentry’s profiling capabilities, but they are currently only supported in select SDKs as described below.
 
 Other platforms are supported via the prior transaction-based Profiling product, but these will not benefit from new capabilities introduced by Continuous and UI Profiling (direct start/stop control over the profile lifecycle and removal of duration limits). For more information on the differences between transaction-based Profiling and Continuous/UI Profiling, read [this documentation](/product/explore/profiling/transaction-vs-continuous-profiling).
 
@@ -30,10 +30,11 @@ Continuous Profiling can be used both independently and as a complement to the t
 
 <Alert>
 
-UI Profiling can be used both independently and as a complement to the tracing product. Support for Browser JavaScript is coming soon.
+UI Profiling can be used both independently and as a complement to the tracing product.
 
 </Alert>
 
+- [Browser JavaScript](/platforms/javascript/profiling/) [beta] (since version `10.27.0`)
 - Mobile
   - [Android](/platforms/android/profiling/#continuous-profiling)
   - [iOS and macOS](/platforms/apple/guides/ios/profiling/#continuous-profiling)
diff --git a/platform-includes/profiling/automatic-instrumentation-setup/_default.mdx b/platform-includes/profiling/automatic-instrumentation-setup/_default.mdx
@@ -16,11 +16,8 @@ Sentry.init({
   // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
   tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
 
-  // Set profilesSampleRate to 1.0 to profile every transaction.
-  // Since profilesSampleRate is relative to tracesSampleRate,
-  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
-  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
-  // result in 25% of transactions being profiled (0.5*0.5=0.25)
-  profilesSampleRate: 1.0,
+  // Set profileSessionSampleRate to 1.0 to profile during every session.
+  // The decision, whether to profile or not, is made once per session (when the SDK is initialized).
+  profileSessionSampleRate: 1.0,
 });
 ```
diff --git a/platform-includes/profiling/automatic-instrumentation-setup/javascript.angular.mdx b/platform-includes/profiling/automatic-instrumentation-setup/javascript.angular.mdx
@@ -16,11 +16,8 @@ Sentry.init({
   // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
   tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
 
-  // Set profilesSampleRate to 1.0 to profile every transaction.
-  // Since profilesSampleRate is relative to tracesSampleRate,
-  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
-  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
-  // result in 25% of transactions being profiled (0.5*0.5=0.25)
-  profilesSampleRate: 1.0,
+  // Set profileSessionSampleRate to 1.0 to profile during every session.
+  // The decision, whether to profile or not, is made once per session (when the SDK is initialized).
+  profileSessionSampleRate: 1.0,
 });
 ```
diff --git a/platform-includes/profiling/automatic-instrumentation-setup/javascript.astro.mdx b/platform-includes/profiling/automatic-instrumentation-setup/javascript.astro.mdx
@@ -15,11 +15,8 @@ Sentry.init({
   // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
   tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
 
-  // Set profilesSampleRate to 1.0 to profile every transaction.
-  // Since profilesSampleRate is relative to tracesSampleRate,
-  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
-  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
-  // result in 25% of transactions being profiled (0.5*0.5=0.25)
-  profilesSampleRate: 1.0,
+  // Set profileSessionSampleRate to 1.0 to profile during every session.
+  // The decision, whether to profile or not, is made once per session (when the SDK is initialized).
+  profileSessionSampleRate: 1.0,
 });
 ```
diff --git a/platform-includes/profiling/automatic-instrumentation-setup/javascript.nextjs.mdx b/platform-includes/profiling/automatic-instrumentation-setup/javascript.nextjs.mdx
@@ -15,11 +15,8 @@ Sentry.init({
   // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
   tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
 
-  // Set profilesSampleRate to 1.0 to profile every transaction.
-  // Since profilesSampleRate is relative to tracesSampleRate,
-  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
-  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
-  // result in 25% of transactions being profiled (0.5*0.5=0.25)
-  profilesSampleRate: 1.0,
+  // Set profileSessionSampleRate to 1.0 to profile during every session.
+  // The decision, whether to profile or not, is made once per session (when the SDK is initialized).
+  profileSessionSampleRate: 1.0,
 });
 ```
diff --git a/platform-includes/profiling/automatic-instrumentation-setup/javascript.nuxt.mdx b/platform-includes/profiling/automatic-instrumentation-setup/javascript.nuxt.mdx
@@ -15,11 +15,8 @@ Sentry.init({
   // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
   tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
 
-  // Set profilesSampleRate to 1.0 to profile every transaction.
-  // Since profilesSampleRate is relative to tracesSampleRate,
-  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
-  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
-  // result in 25% of transactions being profiled (0.5*0.5=0.25)
-  profilesSampleRate: 1.0,
+  // Set profileSessionSampleRate to 1.0 to profile during every session.
+  // The decision, whether to profile or not, is made once per session (when the SDK is initialized).
+  profileSessionSampleRate: 1.0,
 });
 ```
diff --git a/platform-includes/profiling/automatic-instrumentation-setup/javascript.react.mdx b/platform-includes/profiling/automatic-instrumentation-setup/javascript.react.mdx
@@ -16,11 +16,8 @@ Sentry.init({
   // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
   tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
 
-  // Set profilesSampleRate to 1.0 to profile every transaction.
-  // Since profilesSampleRate is relative to tracesSampleRate,
-  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
-  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
-  // result in 25% of transactions being profiled (0.5*0.5=0.25)
-  profilesSampleRate: 1.0,
+  // Set profileSessionSampleRate to 1.0 to profile during every session.
+  // The decision, whether to profile or not, is made once per session (when the SDK is initialized).
+  profileSessionSampleRate: 1.0,
 });
 ```
diff --git a/platform-includes/profiling/automatic-instrumentation-setup/javascript.remix.mdx b/platform-includes/profiling/automatic-instrumentation-setup/javascript.remix.mdx
@@ -16,11 +16,8 @@ Sentry.init({
   // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
   tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
 
-  // Set profilesSampleRate to 1.0 to profile every transaction.
-  // Since profilesSampleRate is relative to tracesSampleRate,
-  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
-  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
-  // result in 25% of transactions being profiled (0.5*0.5=0.25)
-  profilesSampleRate: 1.0,
+  // Set profileSessionSampleRate to 1.0 to profile during every session.
+  // The decision, whether to profile or not, is made once per session (when the SDK is initialized).
+  profileSessionSampleRate: 1.0,
 });
 ```
diff --git a/platform-includes/profiling/automatic-instrumentation-setup/javascript.svelte.mdx b/platform-includes/profiling/automatic-instrumentation-setup/javascript.svelte.mdx
@@ -16,11 +16,8 @@ Sentry.init({
   // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
   tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
 
-  // Set profilesSampleRate to 1.0 to profile every transaction.
-  // Since profilesSampleRate is relative to tracesSampleRate,
-  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
-  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
-  // result in 25% of transactions being profiled (0.5*0.5=0.25)
-  profilesSampleRate: 1.0,
+  // Set profileSessionSampleRate to 1.0 to profile during every session.
+  // The decision, whether to profile or not, is made once per session (when the SDK is initialized).
+  profileSessionSampleRate: 1.0,
 });
 ```
diff --git a/platform-includes/profiling/automatic-instrumentation-setup/javascript.sveltekit.mdx b/platform-includes/profiling/automatic-instrumentation-setup/javascript.sveltekit.mdx
@@ -15,11 +15,8 @@ Sentry.init({
   // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
   tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
 
-  // Set profilesSampleRate to 1.0 to profile every transaction.
-  // Since profilesSampleRate is relative to tracesSampleRate,
-  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
-  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
-  // result in 25% of transactions being profiled (0.5*0.5=0.25)
-  profilesSampleRate: 1.0,
+  // Set profileSessionSampleRate to 1.0 to profile during every session.
+  // The decision, whether to profile or not, is made once per session (when the SDK is initialized).
+  profileSessionSampleRate: 1.0,
 });
 ```
diff --git a/platform-includes/profiling/automatic-instrumentation-setup/javascript.vue.mdx b/platform-includes/profiling/automatic-instrumentation-setup/javascript.vue.mdx
@@ -16,11 +16,8 @@ Sentry.init({
   // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
   tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
 
-  // Set profilesSampleRate to 1.0 to profile every transaction.
-  // Since profilesSampleRate is relative to tracesSampleRate,
-  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
-  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
-  // result in 25% of transactions being profiled (0.5*0.5=0.25)
-  profilesSampleRate: 1.0,
+  // Set profileSessionSampleRate to 1.0 to profile during every session.
+  // The decision, whether to profile or not, is made once per session (when the SDK is initialized).
+  profileSessionSampleRate: 1.0,
 });
 ```
diff --git a/platform-includes/profiling/browser-profiling/javascript.mdx b/platform-includes/profiling/browser-profiling/javascript.mdx
@@ -14,9 +14,9 @@ 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 <PlatformSdkPackageName fallback="@sentry/browser"/> SDK, minimum version 7.60.0
+- Install the <PlatformSdkPackageName fallback="@sentry/browser"/> 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 `profilesSampleRate`
+- Configure the SDK to use the `browserProfilingIntegration` and set `profileSessionSampleRate` (UI Profiling) or `profilesSampleRate` (deprecated transaction-based Profiling)
 
 ## Step 1: Install the <PlatformOrGuideName/> SDK
 
@@ -48,10 +48,49 @@ Configuration should happen as early as possible in your application's lifecycle
 
 <Alert level="warning" title="Local Profiling with Chrome DevTools">
 
-When you enable `browserProfilingIntegration` in your SDK configuration, Chrome will incorrectly attribute regular rendering work as “Profiling Overhead” if you are doing local profiling via the Chrome DevTools Performance panel. To avoid this, disable or remove the integration when profiling with Chrome DevTools. 
+When you enable `browserProfilingIntegration` in your SDK configuration, Chrome will incorrectly attribute regular rendering work as “Profiling Overhead” if you are doing local profiling via the Chrome DevTools Performance panel. To avoid this, disable or remove the integration when profiling with Chrome DevTools.
 
 </Alert>
 
+## Profiling Modes
+
+Profiling supports two modes: `manual` and `trace`. These modes are mutually exclusive and cannot be used at the same time.
+
+In `manual` mode, you can manage the profiling data collection via calls to `Sentry.uiProfiler.startProfiler` and `Sentry.uiProfiler.stopProfiler`. You have full control over when the profiler runs.
+
+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.
+
+After enabling the `browserProfilingIntegration` and setting a `profileSessionSampleRate`, you can start and stop the profiler with the following calls:
+
+```javascript {9}
+// All spans (unless those discarded by sampling) will have profiling data attached to them.
+Sentry.uiProfiler.startProfiler();
+// Code executed between these two calls will be profiled
+Sentry.uiProfiler.stopProfiler();
+```
+
+### Trace Lifecycle Profiling
+
+To enable trace lifecycle profiling, <PlatformLink to="/tracing">enable tracing</PlatformLink> and set `profileLifecycle` to `'trace'` in your SDK configuration.
+
+```javascript {9}
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [
+    Sentry.browserTracingIntegration(), // Enables tracing
+    Sentry.browserProfilingIntegration()
+  ],
+  tracesSampleRate: 1.0, // Enables tracing
+  profileSessionSampleRate: 1.0,
+  profileLifecycle: 'trace',
+});
+```
+
 ## The Difference Between DevTools & Sentry's JavaScript Browser Profiler
 
 What does Sentry's JavaScript browser profile offer that Chrome DevTools does not?
diff --git a/platform-includes/profiling/node-profiling/javascript.mdx b/platform-includes/profiling/node-profiling/javascript.mdx
@@ -26,7 +26,7 @@ The version of the `@sentry/profiling-node` package must match the version of th
 
 ## Enabling Profiling
 
-Profiling supports two modes - `manual` and `trace`. The two modes are mutually exclusive, and cannot be used at the same time.
+Profiling supports two modes: `manual` and `trace`. These modes are mutually exclusive and cannot be used at the same time.
 
 In `manual` mode, the profiling data collection can be managed via calls to `Sentry.profiler.startProfiler` and `Sentry.profiler.stopProfiler`. You are entirely in the in control of when the profiler runs.
 
