You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
29
55
30
56
## Identifying Current API Usage
31
57
32
-
If you are specifying either the `profiles_sample_rate`or `profiles_sampler` configuration options, you are using transaction-based profiling.
58
+
If you are specifying either the `profiles_sample_rate` or `profiles_sampler` configuration options, you are using transaction-based profiling.
33
59
34
-
If you are specifying the `profile_session_sample_rate` and/or `profile_lifecycle` configuration options, you are using Continuous Profiling or UI Profiling.
60
+
If you are specifying the `profile_session_sample_rate` and/or `profile_lifecycle` configuration options, you are using Continuous Profiling or UI Profiling.
35
61
36
62
## Migrating to Continuous/UI Profiling
37
63
38
64
### 1. Replace the `profiles_sample_rate` and `profiles_sampler` SDK configuration options with `profile_session_sample_rate`
39
65
40
-
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.
66
+
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.
41
67
42
-
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`.
68
+
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`.
43
69
44
70
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:
45
71
46
72
-**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.)
47
-
- 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.
48
-
- Sampling would only be re-evaluated once an instance restarts or is re-deployed
49
-
-**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.
50
-
- 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.
51
-
- 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.
52
-
73
+
- 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.
74
+
- Sampling would only be re-evaluated once an instance restarts or is re-deployed
75
+
-**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.
76
+
- 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.
77
+
- 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.
78
+
53
79
### 2. Set the new `profile_lifecycle` SDK configuration option
54
80
55
-
Continuous/UI Profiling support two lifecycle modes: `manual` and `trace`.
81
+
Continuous/UI Profiling support two lifecycle modes: `manual` and `trace`.
56
82
57
83
**`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.
Copy file name to clipboardExpand all lines: platform-includes/profiling/browser-profiling/javascript.mdx
+11-11Lines changed: 11 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,24 +14,25 @@ Note that since the profiling API is currently only exposed in Chromium, profile
14
14
15
15
To get started with JavaScript browser profiling, you'll need to:
16
16
17
-
- Install the <PlatformSdkPackageNamefallback="@sentry/browser"/> SDK, minimum version `10.27.0` (UI Profiling) or `7.60.0` (deprecated transaction-based Profiling)
18
-
- Configure the document response header to include `Document-Policy: js-profiling`
19
-
- Configure the SDK to use the `browserProfilingIntegration` and set `profileSessionSampleRate` (UI Profiling) or `profilesSampleRate` (deprecated transaction-based Profiling)
Install our <PlatformOrGuideName/> SDK using either `yarn` or `npm`, the minimum version that supports profiling is **7.60.0**.
19
+
-Install the <PlatformSdkPackageNamefallback="@sentry/browser"/> 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**.
25
+
-Install the <PlatformSdkPackageNamefallback="@sentry/electron"/> SDK, minimum version `7.4.0` (UI Profiling) or `4.16.0` (deprecated transaction-based Profiling)
32
26
33
27
</PlatformSection>
34
28
29
+
- Configure the document response header to include `Document-Policy: js-profiling`
30
+
- Configure the SDK to use the `browserProfilingIntegration` and set `profileSessionSampleRate` (UI Profiling) or `profilesSampleRate` (deprecated transaction-based Profiling)
31
+
32
+
## Step 1: Install the <PlatformOrGuideName/> SDK
33
+
34
+
Install our <PlatformOrGuideName/> SDK using either `npm`, `yarn`, or `pnpm`.
@@ -60,7 +61,6 @@ In `manual` mode, you can manage the profiling data collection via calls to `Sen
60
61
61
62
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.
62
63
63
-
64
64
### Manual Lifecycle Profiling
65
65
66
66
Manual lifecycle profiling is the default mode and enables you to start and stop the profiler manually.
0 commit comments