Set Up Profiling

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.

Enable Tracing

Profiling depends on Sentry’s Tracing product being enabled beforehand. To enable tracing in the SDK:

In AndroidManifest.xml:

<application>
  <meta-data
    android:name="io.sentry.dsn"
    android:value="https://examplePublicKey@o0.ingest.sentry.io/0"
  />
  <meta-data
    android:name="io.sentry.traces.sample-rate"
    android:value="1.0"
  />
</application>

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.

Enable Profiling

In AndroidManifest.xml:

<application>
  <meta-data
    android:name="io.sentry.dsn"
    android:value="https://examplePublicKey@o0.ingest.sentry.io/0"
  />
  <meta-data
    android:name="io.sentry.traces.sample-rate"
    android:value="1.0"
  />
  <meta-data
    android:name="io.sentry.traces.profiling.sample-rate"
    android:value="1.0"
  />
  <meta-data
    android:name="io.sentry.traces.profiling.enable-app-start"
    android:value="true"
  />
</application>

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.

Continuous Profiling

(New in version 8.5.0)

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.

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.

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.

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.

<application>
  <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"
  />
  <meta-data
    android:name="io.sentry.traces.profiling.start-on-app-start"
    android:value="true"
  />
</application>

Or, if you are manually instrumenting Sentry:

import io.sentry.android.core.SentryAndroid;

SentryAndroid.init(this, options -> {
  options.setDsn("https://examplePublicKey@o0.ingest.sentry.io/0");
  // 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();