Quickstart: Callstack sampling on Android

Prerequisites

Capture a CPU profile

Linux or macOS

Make sure adb is installed and in your PATH.

adb devices -l

If more than one device or emulator is reported you must select one upfront as follows:

export ANDROID_SERIAL=SER123456

Download cpu_profile (if you don't have a Perfetto checkout):

curl -LO https://raw.githubusercontent.com/google/perfetto/master/tools/cpu_profile chmod +x cpu_profile

Then, start profiling. For example, to profile the processes com.android.foo and com.android.bar, use:

./cpu_profile -n "com.android.foo,com.android.bar"

By default, profiling runs until manually terminated manually. To set a specific duration for recording (e.g. 30 seconds), use:

./cpu_profile -n "com.android.foo,com.android.bar" -d 30000

To change how frequently stack samples are recorded (e.g. 120 samples per second), set the -f argument:

./cpu_profile -n "com.android.foo,com.android.bar" -f 120

You can also pass in parts of the names of the processes you want to profile by enabling --partial-matching/-p. This matches processes that are already running when profiling is started. For instance, to profile the processes com.android.foo and com.android.bar, run:

./cpu_profile -n "foo,bar" -p

You can also pass in a custom Perfetto config, which overrides all of the options above, using the -c argument:

./cpu_profile -c "path/to/perfetto.config"

To change where profiles are output, use the -o argument:

./cpu_profile -n "com.android.foo,com.android.bar" -o "path/to/output/directory"

Windows

Make sure that the downloaded adb.exe is in the PATH.

set PATH=%PATH%;%USERPROFILE%\Downloads\platform-tools adb devices -l

If more than one device or emulator is reported you must select one upfront as follows:

set ANDROID_SERIAL=SER123456

Download the cpu_profile script. Then, start profiling. For example, to profile the processes com.android.foo and com.android.bar, use:

python3 /path/to/cpu_profile -n "com.android.foo,com.android.bar"

Please see the Linux or maxOS section for more examples.

Symbolization

You may need to symbolize the collected profiles if they are missing symbols. See this for more details on how to do this.

For example, to profile and symbolize the profiles for the process com.android.foo, run:

PERFETTO_SYMBOLIZER_MODE=index PERFETTO_BINARY_PATH=path/to/directory/with/symbols/ ./cpu_profile -n "com.android.foo"

View profile

Visualizing callstacks in the Perfetto UI is currently disabled behind a flag. Please enable it before proceeding further:

Enable flame graph flag

Upload the raw-trace or symbolized-trace file from the output directory to the Perfetto UI and click on one of the diamond markers in the UI track named "Perf Samples" for the processes that you selected for profiling. Each diamond marker represents a profile with stack samples recorded from the beginning of the trace up until that diamond marker on the timeline.

Profile Diamond Native Flamegraph

cpu_profile will also write separate profiles for each process that it profiled in the output directory, and those can be visualized using pprof.