1# Quickstart: Callstack sampling on Android 2 3## Prerequisites 4 5- [ADB](https://developer.android.com/studio/command-line/adb) installed. 6- A device running Android T+. 7- Either a debuggable (`userdebug`/`eng`) Android image, or the apps to be 8 profiled need to be 9 [marked as profileable or debuggable](https://developer.android.com/guide/topics/manifest/profileable-element) 10 in their manifests. 11 12## Capture a CPU profile 13 14### Linux or macOS 15 16Make sure `adb` is installed and in your `PATH`. 17 18```bash 19adb devices -l 20``` 21 22If more than one device or emulator is reported you must select one upfront as 23follows: 24 25```bash 26export ANDROID_SERIAL=SER123456 27``` 28 29Download `cpu_profile` (if you don't have a Perfetto checkout): 30 31```bash 32curl -LO https://raw.githubusercontent.com/google/perfetto/main/tools/cpu_profile 33chmod +x cpu_profile 34``` 35 36Then, start profiling. For example, to profile the processes `com.android.foo` 37and `com.android.bar`, use: 38 39```bash 40./cpu_profile -n "com.android.foo,com.android.bar" 41``` 42 43By default, profiling runs until manually terminated manually. To set a specific 44duration for recording (e.g. 30 seconds), use: 45 46```bash 47./cpu_profile -n "com.android.foo,com.android.bar" -d 30000 48``` 49 50To change how frequently stack samples are recorded (e.g. 120 samples per 51second), set the `-f` argument: 52 53```bash 54./cpu_profile -n "com.android.foo,com.android.bar" -f 120 55``` 56 57You can also pass in parts of the names of the processes you want to profile by 58enabling `--partial-matching/-p`. This matches processes that are already 59running when profiling is started. For instance, to profile the processes 60`com.android.foo` and `com.android.bar`, run: 61 62```bash 63./cpu_profile -n "foo,bar" -p 64``` 65 66You can also pass in a custom [Perfetto config](/docs/concepts/config.md), which 67overrides all of the options above, using the `-c` argument: 68 69```bash 70./cpu_profile -c "path/to/perfetto.config" 71``` 72 73To change where profiles are output, use the `-o` argument: 74 75```bash 76./cpu_profile -n "com.android.foo,com.android.bar" -o "path/to/output/directory" 77``` 78 79### Windows 80 81Make sure that the downloaded `adb.exe` is in the `PATH`. 82 83```bash 84set PATH=%PATH%;%USERPROFILE%\Downloads\platform-tools 85 86adb devices -l 87``` 88 89If more than one device or emulator is reported you must select one upfront as 90follows: 91 92```bash 93set ANDROID_SERIAL=SER123456 94``` 95 96Download the 97[`cpu_profile`](https://raw.githubusercontent.com/google/perfetto/main/tools/cpu_profile) 98script. Then, start profiling. For example, to profile the processes 99`com.android.foo` and `com.android.bar`, use: 100 101```bash 102python3 /path/to/cpu_profile -n "com.android.foo,com.android.bar" 103``` 104 105Please see the [Linux or maxOS section](#linux-or-macos) for more examples. 106 107## Symbolization 108 109You may need to symbolize the collected profiles if they are missing symbols. 110See [this](/docs/data-sources/native-heap-profiler#symbolize-your-profile) for 111more details on how to do this. 112 113For example, to profile and symbolize the profiles for the process 114`com.android.foo`, run: 115 116```bash 117PERFETTO_SYMBOLIZER_MODE=index PERFETTO_BINARY_PATH=path/to/directory/with/symbols/ ./cpu_profile -n "com.android.foo" 118``` 119 120## View profile 121 122Upload the `raw-trace` or `symbolized-trace` file from the output directory to 123the [Perfetto UI](https://ui.perfetto.dev) and click and drag over one or more 124of the diamond markers in the UI track named "Perf Samples" for the processes 125that you selected for profiling. Each diamond marker represents a snapshot of 126the call-stack at that point on the timeline. 127 128 129 130 131`cpu_profile` will also write separate profiles for each process that it 132profiled in the output directory, and those can be visualized using 133[`pprof`](https://github.com/google/pprof). You can merge them into one by 134passing all of them to pprof, e.g. 135`pprof /tmp/perf_profile-240105114948clvad/*`. 136
