diff --git a/docs/platforms/android/configuration/options.mdx b/docs/platforms/android/configuration/options.mdx index 8854596a5a0b8..31fb0961b3098 100644 --- a/docs/platforms/android/configuration/options.mdx +++ b/docs/platforms/android/configuration/options.mdx @@ -301,54 +301,56 @@ Set this boolean to `false` to disable tracing for `OPTIONS` requests. This opti -## Profiling Options +## UI Profiling Options - + -A number between `0` and `1`, controlling the percentage chance a given profile will be sent to Sentry. (`0` represents 0% while `1` represents 100%.) Applies only to sampled transactions created in the app. Either this or must be defined to enable transaction profiling. Don't set it if you want to use Continuous Profiling. +UI Profiling requires SDK versions `8.7.0` or higher. Lower versions can use the transaction-based profiling. - + - + -A function responsible for determining the percentage chance a given profile will be sent to Sentry. It will automatically be passed information about the transaction and the context in which it's being created, and must return a number between `0` (0% chance of being sent) and `1` (100% chance of being sent). Can also be used for filtering profiles, by returning 0 for those that are unwanted. Either this or must be defined to enable transaction profiling. Don't set it if you want to use Continuous Profiling. +A number between `0` and `1`, controlling the percentage chance that the session will be profiled. `0` represents 0% while `1` represents 100%. The default is null (disabled). - + -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 or must be defined. +Whether the UI profiling lifecycle is controlled manually or based on the trace lifecycle. Possible values are: + +- `manual`: **default** Profiler must be started and stopped through `Sentry.startProfiler()` and `Sentry.stopProfiler()` APIs +- `trace`: Profiler is started and stopped automatically whenever a sampled trace starts or finishes -## Continuous Profiling Options + - +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. -This feature is experimental and may have bugs. +- 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 - + - +## Transaction-Based Profiling Options -A number between `0` and `1`, controlling the percentage chance the session will be profiled. `0` represents 0% while `1` represents 100%. The default is null (disabled). and must not be set to enable Continuous 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` profile lifecycle option. In order to upgrade to UI Profiling, you also need to remove the transaction-based options from your configuration. - + - +A number between `0` and `1`, controlling the percentage chance that a given profile will be sent to Sentry. (`0` represents 0% while `1` represents 100%.) Applies only to sampled transactions created in the app. Setting this option will enable the legacy profiler. -Whether the profiling lifecycle is controlled manually or based on the trace lifecycle. Possible values are: + -- `manual`: **default** Profiler must be started and stopped through `Sentry.startProfiler()` and `Sentry.stopProfiler()` APIs -- `trace`: Profiler is started and stopped automatically whenever a sampled trace starts and finishes + - +A function responsible for determining the percentage chance that a given profile will be sent to Sentry. It will automatically be passed information about the transaction and the context in which it's being created, and must return a number between `0` (0% chance of being sent) and `1` (100% chance of being sent). Can also be used for filtering profiles, by returning 0 for those that are unwanted. Either this or must be defined to enable transaction profiling. Setting this option will enable the legacy profiler. - + -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. + -- 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 +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. diff --git a/docs/platforms/android/index.mdx b/docs/platforms/android/index.mdx index d84d9c6fd86ed..61c8ea27a7a0b 100644 --- a/docs/platforms/android/index.mdx +++ b/docs/platforms/android/index.mdx @@ -30,10 +30,7 @@ Select which Sentry features you'd like to install in addition to Error Monitori options={[ 'error-monitoring', 'performance', - { - id: 'profiling', - checked: false - }, + 'profiling', 'session-replay' ]} /> @@ -83,13 +80,13 @@ Configuration is done via the application `AndroidManifest.xml`. Here's an examp - + - - + + - + @@ -108,15 +105,11 @@ import io.sentry.Sentry; public class MyActivity extends AppCompatActivity { protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); - // Any code running after this line will be - //profiled until Sentry.stopProfiler() is called. - Sentry.startProfiler(); try { throw new Exception("This is a test."); } catch (Exception e) { Sentry.captureException(e); } - Sentry.stopProfiler(); } } ``` @@ -129,15 +122,11 @@ import io.sentry.Sentry class MyActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) - // Any code running after this line will be - //profiled until Sentry.stopProfiler() is called. - Sentry.startProfiler() try { throw Exception("This is a test.") } catch (e: Exception) { Sentry.captureException(e) } - Sentry.stopProfiler() } } ``` diff --git a/docs/platforms/android/profiling/index.mdx b/docs/platforms/android/profiling/index.mdx index beba0bad91fd6..d59e174e38c27 100644 --- a/docs/platforms/android/profiling/index.mdx +++ b/docs/platforms/android/profiling/index.mdx @@ -11,139 +11,244 @@ sidebar_order: 5000 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. -## Enable Tracing +## Installation -Profiling depends on Sentry’s Tracing product being enabled beforehand. To enable tracing in the SDK: +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. -In `AndroidManifest.xml`: +## Enabling UI Profiling -```xml - - - - -``` +UI Profiling supports two modes - `manual` and `trace`. The two modes are mutually exclusive, and cannot be used at the same time. -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. +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. -## Enable Profiling +In `trace` mode, the profiler manages its own start and stop calls, which are based on spans: the profiler continues to run while there is at least one active sampled span, and stops when there are no active sampled spans. - +Sentry SDK supports an additional `profileSessionSampleRate` that will enable or disable profiling for the entire session. This sampling decision is evaluated only once per session. -Android 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`. +### Enabling Trace Lifecycle UI Profiling - +To enable trace profiling, set the lifecycle to `trace`. Trace profiling requires tracing to be enabled. -In `AndroidManifest.xml`: +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 +```xml {filename:AndroidManifest.xml} + - - + + + + + ``` - - -The `io.sentry.traces.profiling.sample-rate` setting is _relative_ to the `io.sentry.traces.sample-rate` setting. - - - -## App Start Profiling - -When app start profiling is enabled, the whole app start process is profiled. -This includes all methods from any `ContentProvider`, the `Application` class, and the first Activity, until the first automatic Activity transaction is finished. -App start profiling can be enabled with the manifest option `io.sentry.traces.profiling.enable-app-start` as shown above, and it will respect the `io.sentry.traces.sample-rate` and the `io.sentry.traces.profiling.sample-rate`. -If you prefer to use a sampling function, the SDK sets the `isForNextAppStart` field on the `TransactionContext` to specify it will be used for the next app start profiling. - - +```java +import io.sentry.ProfileLifecycle; +import io.sentry.android.core.SentryAndroid; -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. +// 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 -## Continuous Profiling +// 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 UI Profiling -This feature is experimental and may have bugs. +To enable manual profiling, set the lifecycle to `manual`. Manual profiling does not require tracing to be enabled. - +```xml {filename:AndroidManifest.xml} + + + + + + + + +``` -_(New in version 8.5.0)_ +```java +import io.sentry.ProfileLifecycle; +import io.sentry.Sentry; +import io.sentry.android.core.SentryAndroid; -The current profiling implementation stops the profiler 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. We now offer an experimental continuous mode, where profiling data is periodically uploaded while running, with no limit to how long the profiler may run. +// 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(); + } +} +``` -Previously, profiles only ran in tandem with performance transactions that were started either automatically or manually with `Sentry.startTransaction`. Now, you can start and stop the profiler directly with `Sentry.startProfiler` and `Sentry.stopProfiler`. You can also start a profile at app launch by setting `SentryOptions.startProfilerOnAppStart = true` in your call to `SentryAndroid.init`. +```kotlin +import io.sentry.ProfileLifecycle +import io.sentry.Sentry +import io.sentry.android.core.SentryAndroid -Continuous profiling requires only the `SentryOptions.profileSessionSampleRate` option to be set when you start the SDK to opt in. If you had previously set `SentryOptions.profilesSampleRate` or `SentryOptions.profilesSampler` to use transaction-based profiling, then remove those lines of code from your configuration. +// 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() + } +} +``` -There are two ways to start the profiler: manually, calling `Sentry.startProfiler` and `Sentry.stopProfiler` to start and stop the profiler, or automatically whenever a sampled trace starts and finishes. The latter behaviour is very similar to the current profiling implementation. You can control this behaviour setting `SentryOptions.profileLifecycle` to `manual` or `trace` in your call to `SentryAndroid.init`. +### Enabling Transaction-Based Profiling - + -Continuous profiling has implications for your org's billing structure. This feature is only available for subscription plans that enrolled after June 5, 2024. +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} - - - + + + + + + + ``` -Or, if you are manually instrumenting Sentry: - - -```java {tabTitle:Java} +```java +import io.sentry.ProfileLifecycle; +import io.sentry.Sentry; import io.sentry.android.core.SentryAndroid; -SentryAndroid.init(this, options -> { - options.setDsn("___PUBLIC_DSN___"); - // Currently under experimental options: - options.getExperimental().setProfileSessionSampleRate(1.0); - // In manual mode, you need to start and stop the profiler manually using Sentry.startProfiler and Sentry.stopProfiler - // In trace mode, the profiler will start and stop automatically whenever a sampled trace starts and finishes - options.getExperimental().setProfileLifecycle(ProfileLifecycle.MANUAL); - // Start profiling automatically as early as possible, to capture app startup - // If profileLifecycle is set to `manual`: stopProfiler must be called manually when the app startup is completed - // If profileLifecycle is set to `trace`: profiling will automatically be stopped when the app start root span ends - options.getExperimental().setStartProfilerOnAppStart(true); -}); -// Start profiling -Sentry.startProfiler(); - -// After all profiling is done, stop the profiler. Profiles can last indefinitely if not stopped. -Sentry.stopProfiler(); +// 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 {tabTitle:Kotlin} +```kotlin +import io.sentry.ProfileLifecycle +import io.sentry.Sentry import io.sentry.android.core.SentryAndroid -SentryAndroid.init(this) { options -> - options.dsn = "___PUBLIC_DSN___" - // Currently under experimental options: - options.experimental.profileSessionSampleRate = 1.0 - // In manual mode, you need to start and stop the profiler manually using Sentry.startProfiler and Sentry.stopProfiler - // In trace mode, the profiler will start and stop automatically whenever a sampled trace starts and finishes - options.experimental.profileLifecycle = ProfileLifecycle.MANUAL - // Start profiling automatically as early as possible, to capture app startup - // If profileLifecycle is set to `manual`: stopProfiler must be called manually when the app startup is completed - // If profileLifecycle is set to `trace`: profiling will automatically be stopped when the app start root span ends - options.experimental.startProfilerOnAppStart = true +// 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 + }) + } } -// Start profiling -Sentry.startProfiler() - -// After all profiling is done, stop the profiler. Profiles can last indefinitely if not stopped. -Sentry.stopProfiler() ``` + + + +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. + +