Set Up Profiling
Learn how to enable profiling in your app if it is not already set up.
With profiling, Sentry tracks your software's performance by sampling your program's call stack in a variety of environments. This feature collects function-level information about your code and enables you to fine-tune your program's performance. Sentry's profiler captures function calls and their exact locations, aggregates them, and shows you the most common code paths of your program. This highlights areas you could optimize to help increase both the performance of your code and increase user satisfaction, as well as drive down costs.
Important
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.
Android profiling is available starting in SDK version 8.7.0. The legacy profiler is available on SDK versions 6.16.0 and higher through its options.
Profiling supports two modes - manual and trace. The two 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.
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.
Note
Continuous profiling has implications for your org's billing structure. This feature is only available for subscription plans that enrolled after June 5, 2024. You can still use the legacy profiling for older plans.
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.
AndroidManifest.xml<application>
<meta-data
android:name="io.sentry.dsn"
android:value="https://examplePublicKey@o0.ingest.sentry.io/0"
/>
<!-- Enable tracing, needed for profiling `trace` mode, adjust in production env -->
<meta-data
android:name="io.sentry.traces.sample-rate"
android:value="1.0"
/>
<!-- Enable profiling, adjust in production env. This is evaluated only once per session -->
<meta-data
android:name="io.sentry.traces.profiling.session-sample-rate"
android:value="1.0"
/>
<meta-data
android:name="io.sentry.traces.profiling.lifecycle"
android:value="trace"
/>
<!-- Enable profiling on app start. The app start profile will be stopped automatically when the app start root span finishes -->
<meta-data
android:name="io.sentry.traces.profiling.start-on-app-start"
android:value="true"
/>
</application>
To enable manual profiling, set the lifecycle to manual. Manual profiling does not require tracing to be enabled.
AndroidManifest.xml<application>
<meta-data
android:name="io.sentry.dsn"
android:value="https://examplePublicKey@o0.ingest.sentry.io/0"
/>
<!-- Enable profiling, adjust in production env. This is evaluated only once per session -->
<meta-data
android:name="io.sentry.traces.profiling.session-sample-rate"
android:value="1.0"
/>
<meta-data
android:name="io.sentry.traces.profiling.lifecycle"
android:value="manual"
/>
<!-- Enable profiling on app start. The app start profile has to be stopped through Sentry.stopProfiler() -->
<meta-data
android:name="io.sentry.traces.profiling.start-on-app-start"
android:value="true"
/>
</application>
Android legacy 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 legacy 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.
AndroidManifest.xml<application>
<meta-data
android:name="io.sentry.dsn"
android:value="https://examplePublicKey@o0.ingest.sentry.io/0"
/>
<!-- Enable tracing, needed for legacy profiling, adjust in production env -->
<meta-data
android:name="io.sentry.traces.sample-rate"
android:value="1.0"
/>
<!-- Enable legacy profiling, adjust in production env. This is relative to traces sample rate -->
<meta-data
android:name="io.sentry.traces.profiling.sample-rate"
android:value="1.0"
/>
<!-- Enable profiling on app start -->
<meta-data
android:name="io.sentry.traces.profiling.enable-app-start"
android:value="true"
/>
</application>
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.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").