1# Quickstart: Record traces on Android 2 3Perfetto allows you to collect system-wide performance traces from Android 4devices from a variety of data sources (kernel scheduler via ftrace, userspace 5instrumentation via atrace and all other data sources listed in this site). 6 7## Starting the tracing services 8 9Perfetto is based on [platform services](/docs/concepts/service-model.md) 10that are available since Android 9 (P) but are enabled by default only since 11Android 11 (R). 12On Android 9 (P) and 10 (Q) you need to do the following to ensure that the 13tracing services are enabled before getting started: 14 15```bash 16# Needed only on Android 9 (P) and 10 (Q) on non-Pixel phones. 17adb shell setprop persist.traced.enable 1 18``` 19 20If you are running a version of Android older than P, you can still capture a 21trace with Perfetto using the `record_android_trace` script. See instructions 22below in the 23[Recording a trace through the cmdline](#recording-a-trace-through-the-cmdline) 24section. 25 26## Recording a trace 27 28Command line tools (usage examples below in this page): 29 30* Using the [`tools/record_android_trace`](/tools/record_android_trace) helper script. 31* Using directly the `/system/bin/perfetto` command on device [[reference](/docs/reference/perfetto-cli.md)]. 32 33UI tools: 34 35* Through the record page in the [Perfetto UI](https://ui.perfetto.dev). 36* Using the on-device [System Tracing App](https://developer.android.com/topic/performance/tracing/on-device) 37 38### Recording a trace through the Perfetto UI 39 40Navigate to [ui.perfetto.dev](https://ui.perfetto.dev/#!/record) and select 41**Record new trace** from the left menu. 42From this page, select and turn on the data sources you want to include in the 43trace. More detail about the different data sources can be found in the 44_Data sources_ section of the docs. 45 46 47 48If you are unsure, start by turning on **Scheduling details** under the **CPU** tab. 49 50Ensure your device is connected and select **Add ADB device**. Once your device 51has successfully paired (you may need to allow USB debugging on the device), select the **Start Recording** button. 52 53Allow time for the trace to be collected (10s by default) and then you should 54see the trace appear. 55 56 57 58Your trace may look different depending on which data sources you enabled. 59 60### Recording a trace through the cmdline 61 62**Prerequisites** 63 64For the cmdline based workflow you will need the `adb` (Android Debug Bridge) 65executable to be in your PATH. ADB binaries for Linux, Mac or Windows can be 66downloaded from https://developer.android.com/studio/releases/platform-tools . 67 68**Using the helper script** 69 70We suggest using the `tools/record_android_trace` script to record traces from 71the command line. It is the equivalent of running `adb shell perfetto` but it 72helps with getting the paths right, auto-pulling the trace once done and opening 73it on the browser. 74Furthermore, on older versions of Android it takes care of sideloading the 75`tracebox` binary to make up for the lack of tracing system services. 76 77If you are already familiar with `systrace` or `atrace`, both cmdline tools 78support a systrace-equivalent syntax: 79 80On Linux and Mac: 81 82```bash 83curl -O https://raw.githubusercontent.com/google/perfetto/main/tools/record_android_trace 84chmod u+x record_android_trace 85 86# See ./record_android_trace --help for more 87./record_android_trace -o trace_file.perfetto-trace -t 30s -b 64mb \ 88sched freq idle am wm gfx view binder_driver hal dalvik camera input res memory 89``` 90 91On Windows: 92 93```bash 94curl -O https://raw.githubusercontent.com/google/perfetto/main/tools/record_android_trace 95python3 record_android_trace -o trace_file.perfetto-trace -t 30s -b 64mb \ 96sched freq idle am wm gfx view binder_driver hal dalvik camera input res memory 97``` 98 99**Using the on-device /system/bin/perfetto command** 100 101Or, if you want to use directly the on-device binary do instead: 102 103```bash 104adb shell perfetto -o /data/misc/perfetto-traces/trace_file.perfetto-trace -t 20s \ 105sched freq idle am wm gfx view binder_driver hal dalvik camera input res memory 106``` 107 108Caveats when using directly the `adb shell perfetto` workflow: 109 110* Ctrl+C, which normally causes a graceful termination of the trace, is not 111 propagated by ADB when using `adb shell perfetto` but only when using an 112 interactive PTY-based session via `adb shell`. 113* On non-rooted devices before Android 12, the config can only be passed as 114 `cat config | adb shell perfetto -c -` (-: stdin) because of over-restrictive 115 SELinux rules. Since Android 12 `/data/misc/perfetto-configs` can be used for 116 storing configs. 117* On devices before Android 10, adb cannot directly pull 118 `/data/misc/perfetto-traces`. Use 119 `adb shell cat /data/misc/perfetto-traces/trace > trace` to work around. 120* When capturing longer traces, e.g. in the context of benchmarks or CI, use 121 `PID=$(perfetto --background)` and then `kill $PID` to stop. 122 123#### Full trace config 124 125The short syntax allows to enable only a subset of the data sources; for full 126control of the trace config, pass the full trace config in input. 127 128See the [_Trace configuration_ page](/docs/concepts/config.md) and the examples 129in each data source doc page for detailed instructions about how to configure 130all the various knobs of Perfetto. 131 132If you are running on a Mac or Linux host, or are using a bash-based terminal 133on Windows, you can use the following: 134 135WARNING: The below command does not work on Android P because the `--txt` option 136was introduced in Q. The binary protobuf format should be used instead; the 137details of this can be found on the 138[_Trace configuration_ page](https://perfetto.dev/docs/concepts/config#pbtx-vs-binary-format). 139 140```bash 141cat<<EOF>config.pbtx 142duration_ms: 10000 143 144buffers: { 145 size_kb: 8960 146 fill_policy: DISCARD 147} 148buffers: { 149 size_kb: 1280 150 fill_policy: DISCARD 151} 152data_sources: { 153 config { 154 name: "linux.ftrace" 155 ftrace_config { 156 ftrace_events: "sched/sched_switch" 157 ftrace_events: "power/suspend_resume" 158 ftrace_events: "sched/sched_process_exit" 159 ftrace_events: "sched/sched_process_free" 160 ftrace_events: "task/task_newtask" 161 ftrace_events: "task/task_rename" 162 ftrace_events: "ftrace/print" 163 atrace_categories: "gfx" 164 atrace_categories: "view" 165 atrace_categories: "webview" 166 atrace_categories: "camera" 167 atrace_categories: "dalvik" 168 atrace_categories: "power" 169 } 170 } 171} 172data_sources: { 173 config { 174 name: "linux.process_stats" 175 target_buffer: 1 176 process_stats_config { 177 scan_all_processes_on_start: true 178 } 179 } 180} 181EOF 182 183./record_android_trace -c config.pbtx -o trace_file.perfetto-trace 184``` 185 186Or alternatively, when using directly the on-device command: 187 188```bash 189cat config.pbtx | adb shell perfetto -c - --txt -o /data/misc/perfetto-traces/trace.perfetto-trace 190``` 191 192Alternatively, first push the trace config file and then invoke perfetto: 193 194```bash 195adb push config.pbtx /data/local/tmp/config.pbtx 196adb shell 'cat /data/local/tmp/config.pbtx | perfetto --txt -c - -o /data/misc/perfetto-traces/trace.perfetto-trace' 197``` 198 199NOTE: because of strict SELinux rules, on non-rooted builds of Android, passing 200directly the file path as `-c /data/local/tmp/config` will fail, hence the 201`-c -` + stdin piping above. From Android 12 (S), `/data/misc/perfetto-configs/` 202can be used instead. 203 204Pull the file using `adb pull /data/misc/perfetto-traces/trace ~/trace.perfetto-trace` 205and open it in the [Perfetto UI](https://ui.perfetto.dev). 206 207NOTE: On devices before Android 10, adb cannot directly pull 208 `/data/misc/perfetto-traces`. Use 209 `adb shell cat /data/misc/perfetto-traces/trace > trace.perfetto-trace` 210 to work around. 211 212The full reference for the `perfetto` cmdline interface can be found 213[here](/docs/reference/perfetto-cli.md). 214
