diff --git a/docs/platforms/android/configuration/options.mdx b/docs/platforms/android/configuration/options.mdx
index 028287290ae31..c167fc0655842 100644
--- a/docs/platforms/android/configuration/options.mdx
+++ b/docs/platforms/android/configuration/options.mdx
@@ -353,6 +353,14 @@ UI Profiling requires SDK versions `8.7.0` or higher. Lower versions can use the
+
+
+On devices running Android 15 (API level 35) or higher, UI Profiling always uses the Android ProfilingManager to capture Perfetto traces. On older devices, this option controls whether the SDK falls back to the legacy `tracer` backend. When `true` (the default), the legacy profiler runs on devices below API level 35. Set it to `false` to disable profiling on those devices entirely.
+
+This option is deprecated and will be removed in the next major release, when only the ProfilingManager (Perfetto) backend will remain.
+
+
+
A number between `0` and `1`, controlling the percentage chance that the session will be profiled. (`0` represents 0%, `1` represents 100%.) The default is null (disabled).
@@ -370,7 +378,7 @@ Whether the UI profiling lifecycle is controlled manually or based on the trace
-A boolean value that determines whether the app start process will be profiled. When true, the startup process, including ContentProviders, Application, and first Activity creation, will be profiled. Note that must be defined.
+A boolean value that determines whether the app start process will be profiled. When true, the startup process, including ContentProviders, Application, and first Activity creation, will be profiled. Note that must be defined. App start profiling is only supported by the legacy profiler, which runs on devices below Android 15 (API level 35). It has no effect with the ProfilingManager (Perfetto) backend used on API level 35 and higher.
- If profileLifecycle is set to `manual`: profiling is started automatically on startup and stopProfiler must be called manually whenever the app startup is deemed to be completed
- If profileLifecycle is set to `trace`: profiling is started automatically on startup, and will automatically be stopped when the root span that is associated with app startup ends
diff --git a/docs/platforms/android/index.mdx b/docs/platforms/android/index.mdx
index 368daf3b21f56..692924a8b2b7a 100644
--- a/docs/platforms/android/index.mdx
+++ b/docs/platforms/android/index.mdx
@@ -40,8 +40,8 @@ Select which Sentry features you'd like to install in addition to Error Monitori
-
- Profiling uses the Android runtime's `tracer` under the hood to sample threads. There are known issues that this `tracer` can cause crashes in certain circumstances. See this troubleshooting entry for more information.
+
+ On Android 15 (API level 35) and higher, profiling uses the Android ProfilingManager to capture Perfetto traces. On older devices, the SDK automatically falls back to the legacy profiler.
@@ -128,8 +128,6 @@ Configuration is done via the application `AndroidManifest.xml`. Here's an examp
-
-
diff --git a/docs/platforms/android/manual-setup/index.mdx b/docs/platforms/android/manual-setup/index.mdx
index 560056ac8bc3a..8f623846a1bd3 100644
--- a/docs/platforms/android/manual-setup/index.mdx
+++ b/docs/platforms/android/manual-setup/index.mdx
@@ -75,8 +75,6 @@ Configuration is done via the application `AndroidManifest.xml`. Here's an examp
-
-
@@ -159,8 +157,6 @@ class MyApplication : Application() {
options.profileSessionSampleRate = 1.0
// set profiling mode. For more info see https://docs.sentry.io/platforms/android/profiling/#enabling-ui-profiling
options.profileLifecycle = ProfileLifecycle.TRACE
- // enable profiling on app start. The app start profile will be stopped automatically when the app start root span finishes
- options.isStartProfilerOnAppStart = true
// record session replays for 100% of errors and 10% of sessions
options.sessionReplay.sessionSampleRate = 0.1
options.sessionReplay.onErrorSampleRate = 1.0
@@ -218,8 +214,6 @@ public class MyApplication extends Application {
options.setProfileSessionSampleRate(1.0);
// set profiling mode. For more info see https://docs.sentry.io/platforms/android/profiling/#enabling-ui-profiling
options.setProfileLifecycle(ProfileLifecycle.TRACE);
- // enable profiling on app start. The app start profile will be stopped automatically when the app start root span finishes
- options.setStartProfilerOnAppStart(true);
// record session replays for 100% of errors and 10% of sessions
options.getSessionReplay().setSessionSampleRate(0.1);
options.getSessionReplay().setOnErrorSampleRate(1.0);
diff --git a/docs/platforms/android/profiling/index.mdx b/docs/platforms/android/profiling/index.mdx
index 69850a690897a..c0d7fc432e023 100644
--- a/docs/platforms/android/profiling/index.mdx
+++ b/docs/platforms/android/profiling/index.mdx
@@ -9,21 +9,22 @@ sidebar_section: features
-
- Profiling uses the Android runtime's `tracer` under the hood to sample threads. There are known issues that this `tracer` can cause crashes in certain circumstances. See this troubleshooting entry for more information.
-
+On Android 15 (API level 35) and higher, Sentry's Android UI Profiling is built on top of the Android ProfilingManager APIs, which capture stack samples as Perfetto traces. This is the recommended way to profile your Android app.
-
- We're working on a more stable profiling solution based on the Android ProfilingManager APIs (Perfetto). Follow the discussion on GitHub for updates.
+
+ On devices running below Android 15, the SDK automatically falls back to the legacy profiler, which samples threads using the Android runtime's `tracer`. That implementation, along with the transaction-based profiler, is now considered legacy. See Legacy Profiling for details, including how to disable it.
-## Installation
+## Prerequisites
+
+UI Profiling is available starting in SDK version `8.7.0`. On **Android 15 (API level 35) or higher**, it uses the ProfilingManager (Perfetto) backend, available starting in SDK version `8.47.0`.
-Android UI Profiling is available starting in SDK version `8.7.0`.
-The transaction-based profiler is available on SDK versions `6.16.0` and higher through its options.
+On devices running below Android 15, the SDK automatically falls back to the legacy profiler. You can turn this fallback off, and disable profiling on those devices entirely, with the `enableLegacyProfiling` option.
## Enabling UI Profiling
+To enable UI Profiling, set a `profileSessionSampleRate` and choose a profile lifecycle. The SDK automatically uses the ProfilingManager (Perfetto) backend on Android 15 (API level 35) and higher, and the legacy profiler on older devices.
+
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.
@@ -48,8 +49,6 @@ By default, some transactions will be created automatically for common operation
-
-
```
@@ -72,8 +71,6 @@ public class MyApplication extends Application {
// Enable UI profiling, adjust in production env. This is evaluated only once per session
options.setProfileSessionSampleRate(1.0);
options.setProfileLifecycle(ProfileLifecycle.TRACE);
- // Enable profiling on app start. The app start profile will be stopped automatically when the app start root span finishes
- options.setStartProfilerOnAppStart(true);
});
}
}
@@ -97,8 +94,6 @@ class MyApplication : Application() {
// Enable UI profiling, adjust in production env. This is evaluated only once per session
options.profileSessionSampleRate = 1.0
options.profileLifecycle = ProfileLifecycle.TRACE
- // Enable profiling on app start. The app start profile will be stopped automatically when the app start root span finishes
- options.isStartProfilerOnAppStart = true
})
}
}
@@ -114,8 +109,6 @@ To enable manual profiling, set the lifecycle to `manual`. Manual profiling does
-
-
```
@@ -137,13 +130,11 @@ public class MyApplication extends Application {
// Enable UI profiling, adjust in production env. This is evaluated only once per session
options.setProfileSessionSampleRate(1.0);
options.setProfileLifecycle(ProfileLifecycle.MANUAL);
- // Enable profiling on app start. The app start profile has to be stopped through Sentry.stopProfiler()
- options.setStartProfilerOnAppStart(true);
});
- // Start profiling, if lifecycle is set to `manual` and startProfilerOnAppStart is set to `true`
+ // Start profiling
Sentry.startProfiler();
- // Stop profiling, if lifecycle is set to `manual` and startProfilerOnAppStart is set to `true`.
- // This call is optional. If you don't stop the profiler, it will keep profiling your application until the process exits.
+ // Stop profiling. This call is optional. If you don't stop the profiler, it will keep
+ // profiling your application until the process exits.
Sentry.stopProfiler();
}
}
@@ -166,95 +157,28 @@ class MyApplication : Application() {
// Enable UI profiling, adjust in production env. This is evaluated only once per session
options.profileSessionSampleRate = 1.0
options.profileLifecycle = ProfileLifecycle.MANUAL
- // Enable profiling on app start. The app start profile has to be stopped through Sentry.stopProfiler()
- options.isStartProfilerOnAppStart = true
})
- // Start profiling, if lifecycle is set to `manual` and startProfilerOnAppStart is set to `true`
+ // Start profiling
Sentry.startProfiler()
- // Stop profiling, if lifecycle is set to `manual` and startProfilerOnAppStart is set to `true`.
- // This call is optional. If you don't stop the profiler, it will keep profiling your application until the process exits.
+ // Stop profiling. This call is optional. If you don't stop the profiler, it will keep
+ // profiling your application until the process exits.
Sentry.stopProfiler()
}
}
```
-### Enabling Transaction-Based Profiling
-
-
-
-This mode will eventually be deprecated, and it's recommended to upgrade to UI Profiling. The same behaviour, without the 30 seconds limitation, can be achieved with the Trace Lifecycle UI Profiling. In order to upgrade to UI Profiling, you also need to remove the transaction-based profiling options from your configuration.
-Android transaction-based profiling is available starting in SDK version `6.16.0` and is supported on API level 22 and up.
-App start profiling is available starting in SDK version `7.3.0`.
-
-
-
-The transaction-based profiling only runs in tandem with performance transactions that were started either automatically or manually with `Sentry.startTransaction`, and stops automatically after 30 seconds (unless you manually stop it earlier). Naturally, this limitation makes it difficult to get full coverage of your app's execution.
-
-```xml {filename:AndroidManifest.xml}
-
-
-
-
-
-
-
-
-
-```
-
-```java
-import io.sentry.ProfileLifecycle;
-import io.sentry.Sentry;
-import io.sentry.android.core.SentryAndroid;
-
-// App main Application class
-public class MyApplication extends Application {
+## Limitations
- @Override
- public void onCreate() {
- super.onCreate();
- SentryAndroid.init(
- this,
- options -> {
- options.setDsn("___PUBLIC_DSN___");
- // Enable tracing, needed for legacy profiling, adjust in production env
- options.setTracesSampleRate(1.0);
- // Enable transaction-based profiling, adjust in production env. This is relative to traces sample rate
- options.setProfilesSampleRate(1.0);
- // Enable profiling on app start
- options.setEnableAppStartProfiling(true);
- });
- }
-}
-```
-
-```kotlin
-import io.sentry.ProfileLifecycle
-import io.sentry.Sentry
-import io.sentry.android.core.SentryAndroid
-
-// App main Application class
-class MyApplication : Application() {
- override fun onCreate() {
- super.onCreate()
- SentryAndroid.init(
- this,
- { options ->
- options.dsn = "___PUBLIC_DSN___"
- // Enable tracing, needed for profiling `trace` mode, adjust in production env
- options.tracesSampleRate = 1.0
- // Enable transaction-based profiling, adjust in production env. This is relative to traces sample rate
- options.profilesSampleRate = 1.0
- // Enable profiling on app start
- options.isEnableAppStartProfiling = true
- })
- }
-}
-```
+On Android 15 (API level 35) and higher, UI Profiling relies on the Android ProfilingManager, so the following limitations apply:
-
+- **Older devices use the legacy profiler.** On devices below Android 15, the SDK automatically falls back to Legacy Profiling, which has different characteristics. You can disable this fallback with the `enableLegacyProfiling` option.
+- **App start profiling is not supported.** The `startProfilerOnAppStart` option has no effect with the ProfilingManager (Perfetto) backend. App start profiling is only supported by the legacy profiler used on devices below Android 15. To learn more, see Legacy Profiling.
+- **Profiling requests are rate limited and not guaranteed to be filled.** Apart from the SDK sampling rate, the Android Framework also restricts profiling, so not every request results in a profile. These limits are outside the SDK's control. To learn more, see the Android ProfilingManager documentation.
-The SDK won't run app start profiling the very first time the app runs, as the SDK won't have read the options by the time the profile should run.
-The SDK will set the `isForNextAppStart` flag in `TransactionContext` if app start profiling is enabled.
+
+ When testing locally, you can disable the Android Framework restrictions with the following shell command:
+ ```bash
+ adb shell device_config put profiling_testing rate_limiter.disabled true
+ ```
diff --git a/docs/platforms/android/profiling/legacy/index.mdx b/docs/platforms/android/profiling/legacy/index.mdx
new file mode 100644
index 0000000000000..fb5ac74a994c6
--- /dev/null
+++ b/docs/platforms/android/profiling/legacy/index.mdx
@@ -0,0 +1,261 @@
+---
+title: Legacy Profiling
+sidebar_title: Legacy Profiling
+description: "Learn about the legacy profilers and how to use them on devices running Android versions earlier than Android 15."
+sidebar_order: 8000
+---
+
+
+ This page documents Sentry's legacy Android profilers. On Android 15 (API level 35) and higher, the recommended ProfilingManager (Perfetto) based UI Profiling (available since SDK version `8.47.0`) is used automatically. On devices below Android 15, the SDK automatically falls back to the legacy profiler documented here.
+
+
+There are two legacy profiling implementations:
+
+- **Legacy UI Profiling**, which samples threads using the Android runtime's `tracer`. It supports the same `manual` and `trace` lifecycle modes as the current UI Profiling, but uses the `tracer` backend instead of the ProfilingManager.
+- **Transaction-based profiling**, the oldest implementation, which runs only alongside performance transactions and is limited to 30 seconds.
+
+
+ Legacy UI Profiling and transaction-based profiling use the Android runtime's
+ `tracer` under the hood to sample threads. There are known issues that this
+ `tracer` can cause crashes in certain circumstances. See this troubleshooting entry for more information. The ProfilingManager (Perfetto) based UI Profiling is not affected by these issues.
+
+
+## Legacy UI Profiling
+
+Legacy UI Profiling is available starting with SDK version `8.7.0` and is supported on API level 21 and up.
+
+The SDK uses the legacy profiler automatically on devices below Android 15 (API level 35); on Android 15 and higher it uses the ProfilingManager (Perfetto) backend instead. Configure UI Profiling exactly as described in the UI Profiling documentation — the same `profileSessionSampleRate` and `profileLifecycle` options apply. To disable the legacy profiler, and turn off profiling on older devices entirely, set `enableLegacyProfiling` to `false`.
+
+UI Profiling supports two modes: `manual` and `trace`. These modes are mutually exclusive and cannot be used at the same time.
+
+In `manual` mode, profiling data collection is managed via calls to `Sentry.startProfiler` and `Sentry.stopProfiler`. You are entirely in control of when the profiler runs.
+
+In `trace` mode, the profiler manages its own start and stop calls, which are based on spans: the profiler runs while there is at least one active sampled span and stops when there are no active sampled spans.
+
+Unlike the ProfilingManager backend, the legacy profiler supports profiling the app start process through the `startProfilerOnAppStart` option.
+
+### Enabling Trace Lifecycle Legacy UI Profiling
+
+To enable trace profiling, set the lifecycle to `trace`. Trace profiling requires tracing to be enabled.
+
+Check out the tracing setup documentation for more detailed information on how to configure sampling. Setting the sample rate to 1.0 means all transactions will be captured.
+
+By default, some transactions will be created automatically for common operations like loading a view controller/activity and app startup.
+
+```xml {filename:AndroidManifest.xml}
+
+
+
+
+
+
+
+
+
+
+```
+
+```java
+import io.sentry.ProfileLifecycle;
+import io.sentry.android.core.SentryAndroid;
+
+// App main Application class
+public class MyApplication extends Application {
+
+ @Override
+ public void onCreate() {
+ super.onCreate();
+ SentryAndroid.init(
+ this,
+ options -> {
+ options.setDsn("___PUBLIC_DSN___");
+ // Enable tracing, needed for profiling `trace` mode, adjust in production env
+ options.setTracesSampleRate(1.0);
+ // Enable UI profiling, adjust in production env. This is evaluated only once per session
+ options.setProfileSessionSampleRate(1.0);
+ options.setProfileLifecycle(ProfileLifecycle.TRACE);
+ // Enable profiling on app start. The app start profile will be stopped automatically when the app start root span finishes
+ options.setStartProfilerOnAppStart(true);
+ });
+ }
+}
+```
+
+```kotlin
+import io.sentry.ProfileLifecycle
+import io.sentry.android.core.SentryAndroid
+
+// App main Application class
+class MyApplication : Application() {
+
+ override fun onCreate() {
+ super.onCreate()
+ SentryAndroid.init(
+ this,
+ { options ->
+ options.dsn = "___PUBLIC_DSN___"
+ // Enable tracing, needed for profiling `trace` mode, adjust in production env
+ options.tracesSampleRate = 1.0
+ // Enable UI profiling, adjust in production env. This is evaluated only once per session
+ options.profileSessionSampleRate = 1.0
+ options.profileLifecycle = ProfileLifecycle.TRACE
+ // Enable profiling on app start. The app start profile will be stopped automatically when the app start root span finishes
+ options.isStartProfilerOnAppStart = true
+ })
+ }
+}
+```
+
+### Enabling Manual Lifecycle Legacy UI Profiling
+
+To enable manual profiling, set the lifecycle to `manual`. Manual profiling does not require tracing to be enabled.
+
+```xml {filename:AndroidManifest.xml}
+
+
+
+
+
+
+
+
+```
+
+```java
+import io.sentry.ProfileLifecycle;
+import io.sentry.Sentry;
+import io.sentry.android.core.SentryAndroid;
+
+// App main Application class
+public class MyApplication extends Application {
+
+ @Override
+ public void onCreate() {
+ super.onCreate();
+ SentryAndroid.init(
+ this,
+ options -> {
+ options.setDsn("___PUBLIC_DSN___");
+ // Enable UI profiling, adjust in production env. This is evaluated only once per session
+ options.setProfileSessionSampleRate(1.0);
+ options.setProfileLifecycle(ProfileLifecycle.MANUAL);
+ // Enable profiling on app start. The app start profile has to be stopped through Sentry.stopProfiler()
+ options.setStartProfilerOnAppStart(true);
+ });
+ // Start profiling, if lifecycle is set to `manual` and startProfilerOnAppStart is set to `true`
+ Sentry.startProfiler();
+ // Stop profiling, if lifecycle is set to `manual` and startProfilerOnAppStart is set to `true`.
+ // This call is optional. If you don't stop the profiler, it will keep profiling your application until the process exits.
+ Sentry.stopProfiler();
+ }
+}
+```
+
+```kotlin
+import io.sentry.ProfileLifecycle
+import io.sentry.Sentry
+import io.sentry.android.core.SentryAndroid
+
+// App main Application class
+class MyApplication : Application() {
+
+ override fun onCreate() {
+ super.onCreate()
+ SentryAndroid.init(
+ this,
+ { options ->
+ options.dsn = "___PUBLIC_DSN___"
+ // Enable UI profiling, adjust in production env. This is evaluated only once per session
+ options.profileSessionSampleRate = 1.0
+ options.profileLifecycle = ProfileLifecycle.MANUAL
+ // Enable profiling on app start. The app start profile has to be stopped through Sentry.stopProfiler()
+ options.isStartProfilerOnAppStart = true
+ })
+ // Start profiling, if lifecycle is set to `manual` and startProfilerOnAppStart is set to `true`
+ Sentry.startProfiler()
+ // Stop profiling, if lifecycle is set to `manual` and startProfilerOnAppStart is set to `true`.
+ // This call is optional. If you don't stop the profiler, it will keep profiling your application until the process exits.
+ Sentry.stopProfiler()
+ }
+}
+```
+
+## Transaction-Based Profiling
+
+
+
+This is the oldest profiling implementation and will eventually be deprecated. We recommend upgrading to the ProfilingManager (Perfetto) based UI Profiling. The same behavior, without the 30 seconds limitation, can be achieved with the trace lifecycle. In order to upgrade, you also need to remove the transaction-based profiling options from your configuration.
+
+Android transaction-based profiling is available starting in SDK version `6.16.0` and is supported on API level 22 and up.
+App start profiling is available starting in SDK version `7.3.0`.
+
+
+
+Transaction-based profiling only runs in tandem with performance transactions that were started either automatically or manually with `Sentry.startTransaction`, and stops automatically after 30 seconds (unless you manually stop it earlier). Naturally, this limitation makes it difficult to get full coverage of your app's execution.
+
+```xml {filename:AndroidManifest.xml}
+
+
+
+
+
+
+
+
+
+```
+
+```java
+import io.sentry.Sentry;
+import io.sentry.android.core.SentryAndroid;
+
+// App main Application class
+public class MyApplication extends Application {
+
+ @Override
+ public void onCreate() {
+ super.onCreate();
+ SentryAndroid.init(
+ this,
+ options -> {
+ options.setDsn("___PUBLIC_DSN___");
+ // Enable tracing, needed for legacy profiling, adjust in production env
+ options.setTracesSampleRate(1.0);
+ // Enable transaction-based profiling, adjust in production env. This is relative to traces sample rate
+ options.setProfilesSampleRate(1.0);
+ // Enable profiling on app start
+ options.setEnableAppStartProfiling(true);
+ });
+ }
+}
+```
+
+```kotlin
+import io.sentry.Sentry
+import io.sentry.android.core.SentryAndroid
+
+// App main Application class
+class MyApplication : Application() {
+ override fun onCreate() {
+ super.onCreate()
+ SentryAndroid.init(
+ this,
+ { options ->
+ options.dsn = "___PUBLIC_DSN___"
+ // Enable tracing, needed for legacy profiling, adjust in production env
+ options.tracesSampleRate = 1.0
+ // Enable transaction-based profiling, adjust in production env. This is relative to traces sample rate
+ options.profilesSampleRate = 1.0
+ // Enable profiling on app start
+ options.isEnableAppStartProfiling = true
+ })
+ }
+}
+```
+
+
+
+The SDK won't run app start profiling the very first time the app runs, as the SDK won't have read the options by the time the profile should run.
+The SDK will set the `isForNextAppStart` flag in `TransactionContext` if app start profiling is enabled.
+
+
diff --git a/docs/platforms/android/profiling/troubleshooting/index.mdx b/docs/platforms/android/profiling/troubleshooting/index.mdx
index 3b0c5f7033574..c41b20ef1d8f8 100644
--- a/docs/platforms/android/profiling/troubleshooting/index.mdx
+++ b/docs/platforms/android/profiling/troubleshooting/index.mdx
@@ -4,13 +4,13 @@ description: "Learn how to troubleshoot your profiling setup."
sidebar_order: 9000
---
-
- We're working on a more stable profiling solution based on the Android ProfilingManager APIs (Perfetto). Follow the discussion on GitHub for updates.
+
+ The crash-related issues below only affect Legacy Profiling, which uses the Android runtime's `tracer`. The recommended ProfilingManager (Perfetto) based UI Profiling is not affected.
## I see an elevated number of crashes in the Android Runtime when profiling is activated
-Profiling uses the Android runtime's `tracer` under the hood to sample threads. There are known issues that this `tracer` can cause crashes in certain circumstances. Read on for more information, and subscribe to this GitHub issue for updates.
+Legacy Profiling uses the Android runtime's `tracer` under the hood to sample threads. There are known issues that this `tracer` can cause crashes in certain circumstances. The recommended ProfilingManager (Perfetto) based UI Profiling avoids these issues. Read on for more information, and subscribe to this GitHub issue for updates.
As of October 2024, two of these crashes (see 1, 2) have been acknowledged and fixed by Google. The fixes are being rolled out to affected devices by Google, but the crashing behavior might still be present on devices that didn't receive the fix yet.