Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/product/explore/logs/getting-started/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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/"
/>
- <LinkWithPlatformIcon
platform="godot"
label="Godot Engine"
url="/platforms/godot/logs/"
/>

## Upcoming SDKs

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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`
- <LinkWithPlatformIcon
platform="python"
label="Python (since version 2.24.1)"
url="/platforms/python/profiling/"
/>
- <LinkWithPlatformIcon
platform="javascript.node"
label="Node.js (since version 9.8.0)"
url="/platforms/javascript/guides/node/profiling/"
/>

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`
- <LinkWithPlatformIcon
platform="apple"
label="iOS & macOS (since version 8.49.0)"
url="/platforms/apple/profiling/"
/>
- <LinkWithPlatformIcon
platform="android"
label="Android (Java & Kotlin only) (since version 8.5.0)"
url="/platforms/android/profiling/"
/>
- <LinkWithPlatformIcon
platform="javascript.browser"
label="Browser JavaScript (since version 10.27.0)"
url="/platforms/javascript/profiling/"
/>
- <LinkWithPlatformIcon
platform="javascript.electron"
label="Electron (since version 7.4.0)"
url="/platforms/javascript/guides/electron/profiling/"
/>

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.

Expand Down
22 changes: 11 additions & 11 deletions platform-includes/profiling/browser-profiling/javascript.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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 `profileSessionSampleRate` (UI Profiling) or `profilesSampleRate` (deprecated transaction-based Profiling)

## Step 1: Install the <PlatformOrGuideName/> SDK

<PlatformSection notSupported={["javascript.electron"]}>

Install our <PlatformOrGuideName/> SDK using either `yarn` or `npm`, the minimum version that supports profiling is **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)

</PlatformSection>

<PlatformSection supported={["javascript.electron"]}>

Install our Electron SDK using either `yarn` or `npm`, the minimum version that supports profiling is **4.16.0**.
- Install the <PlatformSdkPackageName fallback="@sentry/electron"/> SDK, minimum version `7.4.0` (UI Profiling) or `4.16.0` (deprecated transaction-based Profiling)

</PlatformSection>

- 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 <PlatformOrGuideName/> SDK

Install our <PlatformOrGuideName/> SDK using either `npm`, `yarn`, or `pnpm`.

<PlatformContent includePath="profiling/automatic-instrumentation-intro" />

## Step 2: Add Document-Policy: js-profiling header
Expand Down Expand Up @@ -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.
Expand All @@ -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",
});
```

Expand Down
Loading