Profile a Microbenchmark

By default, Microbenchmarks give you information about the timing and allocations of the executed code. If you want to investigate why the measured code is running slowly, you can run the benchmarks with the CPU profiler attached.

To select the profiler configuration, add the instrumentation runner argument androidx.benchmark.profiling.mode with one of MethodTracing, StackSampling, or None argument, as shown in the following snippet.

For more information about the options, see Choose a recording configuration. MethodTracing is the equivalent of "Trace Java Methods", and StackSampling is the equivalent of "Sample Java Methods" as defined in that document.

android {
    defaultConfig {
        // must be one of: 'None', 'StackSampling', or 'MethodTracing'
        testInstrumentationRunnerArguments["androidx.benchmark.profiling.mode"]= 'StackSampling'
    }
}

android {
    defaultConfig {
        // must be one of: 'None', 'StackSampling', or 'MethodTracing'
        testInstrumentationRunnerArguments["androidx.benchmark.profiling.mode"] = "StackSampling"
    }
}

When you profile a benchmark, an output .trace file is copied to the host in the directory alongside JSON results. To inspect profiling results in the CPU Profiler in Android Studio, select File > Open. To learn more about reading and understanding traces, see Inspect Traces.

MethodTracing

Method tracing is useful when you are trying to optimize your code because it can help you identify the methods that take longer to run than others. You can then focus on optimizing the methods that have the most impact on performance.

Profiling occurs in sequence after code measurement, so your test outputs both accurate timing and profiling results.

StackSampling

Sample tracing can also help identify expensive methods without the performance overhead of method tracing. However, if your app enters a method after a call stack has been captured and the method exits before the next capture, then the method call is not logged. To properly track methods with short life cycles, use method tracing instead of sample tracing.

With stack sampling, the benchmark samples call stacks after the warmup is complete. You can control the sample frequency and duration of sampling using instrumentation arguments.

On Android 10 (API 29) and higher, stack sampling uses Simpleperf to sample app callstacks, including C++ code. On Android 9 (API 28) and lower, it uses Debug.startMethodTracingSampling to capture stack samples.

You can configure this profiling mode by adding another instrumentation arguments:

• androidx.benchmark.profiling.sampleFrequency

  • Number of stack samples to capture per second.
  • Argument type: integer
  • Defaults to 1000 samples per second.

• androidx.benchmark.profiling.sampleDurationSeconds

  • Duration of benchmark to run.
  • Argument type: integer
  • Defaults to 5 seconds.

None

This argument doesn't capture a profiling file. Information about timing and allocations are still measured.