How to capture a profile

This page shows how to record a system trace using the ProfilingManager API.

Add dependencies

For the best experience with the ProfilingManager API, add the following Jetpack libraries to your build.gradle.kts file.

Kotlin

   dependencies {
       implementation("androidx.tracing:tracing:1.3.0")
       implementation("androidx.core:core:1.17.0")
   }

Groovy

   dependencies {
       implementation 'androidx.tracing:tracing:1.3.0'
       implementation 'androidx.core:core:1.17.0'
   }

Record a system trace

After adding the required dependencies, use the following code to record a system trace. This example shows a basic setup within an Activity to start and manage a profiling session.

Kotlin

@RequiresApi(Build.VERSION_CODES.VANILLA_ICE_CREAM)
fun sampleRecordSystemTrace() {
    val mainExecutor: Executor =
        Dispatchers.IO.asExecutor() // Your choice of executor for the callback to occur on.
    val resultCallback = Consumer<ProfilingResult> { profilingResult ->
        if (profilingResult.errorCode == ProfilingResult.ERROR_NONE) {
            Log.d(
                "ProfileTest",
                "Received profiling result file=" + profilingResult.resultFilePath
            )
        } else {
            Log.e(
                "ProfileTest",
                "Profiling failed errorcode=" + profilingResult.errorCode + " errormsg=" + profilingResult.errorMessage
            )
        }
    }
    val stopSignal = CancellationSignal()

    val requestBuilder = SystemTraceRequestBuilder()
    requestBuilder.setCancellationSignal(stopSignal)
    requestBuilder.setTag("FOO") // Caller supplied tag for identification
    requestBuilder.setDurationMs(60000)
    requestBuilder.setBufferFillPolicy(BufferFillPolicy.RING_BUFFER)
    requestBuilder.setBufferSizeKb(20971520)
    requestProfiling(applicationContext, requestBuilder.build(), mainExecutor, resultCallback)

    // Wait some time for profiling to start.

    Trace.beginSection("MyApp:HeavyOperation")
    heavyOperation()
    Trace.endSection()

    // Once the interesting code section is profiled, stop profile
    stopSignal.cancel()
}

fun heavyOperation() {
    // Computations you want to profile
}
ProfilingManagerKotlinSnippets.kt

Java

void heavyOperation() {
  // Computations you want to profile
}

void sampleRecordSystemTrace() {
  Executor mainExecutor = Executors.newSingleThreadExecutor();
  Consumer<ProfilingResult> resultCallback =
      new Consumer<ProfilingResult>() {
        @Override
        public void accept(ProfilingResult profilingResult) {
          if (profilingResult.getErrorCode() == ProfilingResult.ERROR_NONE) {
            Log.d(
                "ProfileTest",
                "Received profiling result file=" + profilingResult.getResultFilePath());
          } else {
            Log.e(
                "ProfileTest",
                "Profiling failed errorcode="

                    + profilingResult.getErrorCode()
                    + " errormsg="
                    + profilingResult.getErrorMessage());
          }
        }
      };
  CancellationSignal stopSignal = new CancellationSignal();

  SystemTraceRequestBuilder requestBuilder = new SystemTraceRequestBuilder();
  requestBuilder.setCancellationSignal(stopSignal);
  requestBuilder.setTag("FOO");
  requestBuilder.setDurationMs(60000);
  requestBuilder.setBufferFillPolicy(BufferFillPolicy.RING_BUFFER);
  requestBuilder.setBufferSizeKb(20971520);
  Profiling.requestProfiling(getApplicationContext(), requestBuilder.build(), mainExecutor,
      resultCallback);

  // Wait some time for profiling to start.

  Trace.beginSection("MyApp:HeavyOperation");
  heavyOperation();
  Trace.endSection();

  // Once the interesting code section is profiled, stop profile
  stopSignal.cancel();
}
ProfilingManagerJavaSnippets.java

The sample code sets up and manages the profiling session by going through the following steps:

  1. Set up the executor. Create an Executor to define the thread that will receive the profiling results. Profiling happens in the background. Using a non-UI thread executor helps prevent Application Not Responding (ANR) errors if you add more processing to the callback later.

  2. Handle profiling results. Create a Consumer<ProfilingResult> object. The system uses this object to send profiling results from ProfilingManager back to your app.

  3. Build the profiling request. Create a SystemTraceRequestBuilder to set up your profiling session. This builder lets you customize ProfilingManager trace settings. Customizing the builder is optional; if you don't, the system uses default settings.

    • Define a tag. Use setTag() to add a tag to the trace name. This tag helps you identify the trace.
    • Optional: Set the duration. Use setDurationMs() to specify how long to profile in milliseconds. For example, 60000 sets a 60-second trace. The trace automatically ends after the specified duration if CancellationSignal isn't triggered before that.
    • Choose a buffer policy. Use setBufferFillPolicy() to define how trace data is stored. BufferFillPolicy.RING_BUFFER means that when the buffer is full, new data overwrites the oldest data, keeping a continuous record of recent activity.
    • Set a buffer size. Use setBufferSizeKb() to specify a buffer size for tracing which you can use to control the size of the output trace file.

  4. Optional: Manage the session lifecycle. Create a CancellationSignal. This object lets you stop the profiling session whenever you want, giving you precise control over its length.

  5. Start and receive results. When you call requestProfiling(), ProfilingManager starts a profiling session in the background. Once profiling is done, it sends the ProfilingResult to your resultCallback#accept method. If profiling finishes successfully, the ProfilingResult provides the path where the trace was saved on your device through ProfilingResult#getResultFilePath. You can get this file programmatically or, for local profiling, by running adb pull <trace_path> from your computer.

  6. Add custom trace points. You can add custom trace points in your app's code. In the previous code example, a trace slice named MyApp:HeavyOperation is added using Trace.beginSection() and Trace.endSection(). This custom slice appears in the generated profile, highlighting specific operations within your app.