149 lines
5.0 KiB
Markdown
149 lines
5.0 KiB
Markdown
# Quickstart: Record traces on Android
|
|
|
|
`perfetto` allows you to collect system-wide performance traces from Android
|
|
devices from a variety of data sources (kernel scheduler via ftrace, userspace
|
|
instrumentation via atrace and all other data sources listed in this site).
|
|
|
|
## Starting the tracing services
|
|
|
|
Due to Perfetto's [service-based architecture](/docs/concepts/service-model.md)
|
|
, the `traced` and `traced_probes` services need to be running to record traces.
|
|
|
|
These services are shipped on Android system images by default since Android 9
|
|
(Pie) but are not always enabled by default.
|
|
On Android 9 (P) and 10 (Q) those services are enabled by default only on Pixel
|
|
phones and must be manually enabled on other phones.
|
|
Since Android 11 (R), perfetto services are enabled by default on most devices.
|
|
|
|
To enable perfetto services run:
|
|
|
|
```bash
|
|
# Will start both traced and traced_probes.
|
|
adb shell setprop persist.traced.enable 1
|
|
```
|
|
|
|
## Recording a trace
|
|
|
|
You can collect a trace in the following ways:
|
|
|
|
* Through the record page in the [Perfetto UI](https://ui.perfetto.dev).
|
|
* Using the `perfetto` command line interface [[reference](/docs/reference/perfetto-cli.md)].
|
|
|
|
### Perfetto UI
|
|
|
|
Navigate to ui.perfetto.dev and select **Record new trace**.
|
|
|
|
From this page, select and turn on the data sources you want to include in the trace. More detail about the different data sources can be found in the
|
|
_Data sources_ section of the docs.
|
|
|
|
|
|
|
|
If you are unsure, start by turning on **Scheduling details** under the **CPU** tab.
|
|
|
|
Ensure your device is connected and select **Add ADB device**. Once your device has successfully paired (you may need to allow USB debugging on the device), select the **Start Recording** button.
|
|
|
|
Allow time for the trace to be collected (10s by default) and then you should see the trace appear.
|
|
|
|
|
|
|
|
Your trace may look different depending on which data sources you enabled.
|
|
|
|
### Perfetto cmdline
|
|
|
|
#### Short syntax
|
|
|
|
If you are already familiar with `systrace` or `atrace`, there is an equivalent syntax with `perfetto`:
|
|
|
|
```bash
|
|
adb shell perfetto -o mytrace.pftrace -t 20s sched freq idle am wm gfx view
|
|
```
|
|
|
|
#### Full trace config
|
|
|
|
The short syntax allows to enable only a subset of the data sources; for full
|
|
control of the trace config, pass the full trace config in input.
|
|
|
|
See the [_Trace configuration_ page](/docs/concepts/config.md) and the examples
|
|
in each data source doc page for detailed instructions about how to configure
|
|
all the various knobs of Perfetto.
|
|
|
|
If you are running on a Mac or Linux host, or are using a bash-based terminal
|
|
on Windows, you can use the following:
|
|
|
|
WARNING: The below command does not work on Android P because the `--txt` option
|
|
was introduced in Q. The binary protobuf format should be used instead; the
|
|
details of this can be found on the
|
|
[_Trace configuration_ page](https://perfetto.dev/docs/concepts/config#pbtx-vs-binary-format).
|
|
|
|
```bash
|
|
adb shell perfetto \
|
|
-c - --txt \
|
|
-o /data/misc/perfetto-traces/trace \
|
|
<<EOF
|
|
duration_ms: 10000
|
|
|
|
buffers: {
|
|
size_kb: 8960
|
|
fill_policy: DISCARD
|
|
}
|
|
buffers: {
|
|
size_kb: 1280
|
|
fill_policy: DISCARD
|
|
}
|
|
data_sources: {
|
|
config {
|
|
name: "linux.ftrace"
|
|
ftrace_config {
|
|
ftrace_events: "sched/sched_switch"
|
|
ftrace_events: "power/suspend_resume"
|
|
ftrace_events: "sched/sched_process_exit"
|
|
ftrace_events: "sched/sched_process_free"
|
|
ftrace_events: "task/task_newtask"
|
|
ftrace_events: "task/task_rename"
|
|
ftrace_events: "ftrace/print"
|
|
atrace_categories: "gfx"
|
|
atrace_categories: "view"
|
|
atrace_categories: "webview"
|
|
atrace_categories: "camera"
|
|
atrace_categories: "dalvik"
|
|
atrace_categories: "power"
|
|
}
|
|
}
|
|
}
|
|
data_sources: {
|
|
config {
|
|
name: "linux.process_stats"
|
|
target_buffer: 1
|
|
process_stats_config {
|
|
scan_all_processes_on_start: true
|
|
}
|
|
}
|
|
}
|
|
|
|
EOF
|
|
```
|
|
|
|
In all other cases, first push the trace config file and then invoke perfetto:
|
|
```bash
|
|
adb push config.txt /data/local/tmp/trace_config.txt
|
|
adb shell 'perfetto --txt -c - -o /data/misc/perfetto-traces/trace < /data/local/tmp/trace_config.txt'
|
|
```
|
|
|
|
NOTE: because of strict SELinux rules, on versions of older than Android 11
|
|
(R) passing directly the file path as `-c /data/local/tmp/config` might fail,
|
|
hence the `-c -` + stdin piping above.
|
|
|
|
Pull the file using `adb pull /data/misc/perfetto-traces/trace ~/trace.pftrace`
|
|
and upload to the [Perfetto UI](https://ui.perfetto.dev).
|
|
|
|
The full reference for the `perfetto` cmdline interface can be found
|
|
[here](/docs/reference/perfetto-cli.md).
|
|
|
|
## On-device System Tracing app
|
|
|
|
Since Android 9 (P) it's possible to collect a trace directly from the device
|
|
using the System Tracing app, from Developer Settings.
|
|
|
|
See https://developer.android.com/topic/performance/tracing/on-device for
|
|
instructions.
|