perfetto
is a tool that allows you to collect performance information from
your Android devices via the
Android Debug Bridge (ADB). perfetto
uses various
sources to collect performance traces from your device, such as the following:
ftrace
for information from the kernelatrace
for user-space annotation in services and appsheapprofd
for native memory usage information of services and apps
This page describes how to call perfetto
and configure it to generate the
desired output.
Syntax
This section describes how to use ADB to call perfetto
and generate a trace.
Data source selection
perfetto
includes the following two modes that determine the data sources
it uses to record your trace:
- light mode: can select only a subset of data sources—specifically atrace
and ftrace. However, it offers an interface similar to
systrace
. - normal mode: gets its configuration in a protocol buffer and allows you to
leverage a lot more of the power of
perfetto
by using data sources different to atrace and ftrace.
This section describes the syntax perfetto
requires to generate a trace using
each of the modes described above.
General options
The following table lists the available options when using perfetto
in either
mode.
Option | Description |
---|---|
--background | -d
|
Perfetto immediately exits the command-line interface and continues recording your trace in background. |
--out OUT_FILE | -o OUT_FILE
|
Specifies the desired path to the output trace file, or - for stdout.
perfetto writes the output to the file described in the flags
above. The output format compiles with the format defined in
AOSP trace.proto .
|
--dropbox TAG
|
Uploads your trace via the DropBoxManager API using the tag you specify. |
--no-guardrails
|
Disables protections against excessive resource usage when enabling the
--dropbox flag during testing. |
--reset-guardrails
|
Resets the persistent state of the guardrails and exits (for testing). |
--query
|
Queries the service state and prints it as human-readable text. |
--query-raw
|
Similar to --query, but prints raw proto-encoded bytes of
tracing_service_state.proto. |
--help | -h
|
Prints out help text for the perfetto tool.
|
Light mode
The general syntax for using perfetto
in light mode is as follows:
adb shell perfetto [ --time TIMESPEC ] [ --buffer SIZE ] [ --size SIZE ] [ ATRACE_CAT | FTRACE_GROUP/FTRACE_NAME | FTRACE_GROUP/* ]...
The following table lists the available options when using perfetto
in
light mode.
Option | Description |
---|---|
--time TIME[s|m|h] | -t TIME[s|m|h]
|
Specifies the trace duration in seconds, minutes, or hours.
For example, --time 1m specifies a trace duration of 1 minute.
The default duration is 10 seconds.
|
--buffer SIZE[mb|gb] | -b SIZE[mb|gb]
|
Specifies the ring buffer size in megabytes (mb) or gigabytes (gb).
The default parameter is --buffer 32mb .
|
--size SIZE[mb|gb] | -s SIZE[mb|gb]
|
Specifies the max file size in megabytes (mb) or gigabytes (gb). By
default perfetto uses only in-memory ring-buffer.
|
This is followed by a list of event specifiers
Event | Description |
---|---|
ATRACE_CAT |
Specifies the atrace categories you want to record a trace for.
For example, the following command traces Window Manager using atrace:
adb shell perfetto --out FILE wm To record other categories, see this list of atrace categories. |
FTRACE_GROUP/FTRACE_NAME |
Specifies the ftrace events you want to record a trace for.
For example, the following command traces sched/sched_switch events:
adb shell perfetto --out FILE sched/sched_switch |
Normal mode
The general syntax for using perfetto
in normal mode is as follows:
adb shell perfetto [ --txt ] --config CONFIG_FILE
The following table lists the available options when using perfetto
in normal mode.
Option | Description |
---|---|
--config CONFIG_FILE | -c CONFIG_FILE
|
Specifies the path to a configuration file. In normal mode, some
configurations may be encoded in a configuration protocol buffer. This file
must comply with the protocol buffer schema defined in
AOSP trace_config.proto .
You select and configure the data sources using the
|
--txt
|
Instructs perfetto to parse the config file as pbtxt. This
flag is experimental, and it's not recommended that you enable it
for production. |
Supported data sources
This section describes the different sources that perfetto
uses to generate
your trace.
FTrace
The ftrace data source allows perfetto
to get events from the kernel.
You can enable this source by setting ftrace_config in the DataSourceConfig.
The events that can be enabled include:
-
- sched/sched_switch
- sched/sched_wakeup
- sched/sched_wakeup_new
- sched/sched_process_exec
- sched/sched_process_exit
- sched/sched_process_fork
- sched/sched_process_free
- sched/sched_process_hang
- sched/sched_process_wait
Filesystem events:
Depending on your device, OS version, and kernel, more events might be available. For more information, refer to the config protos.
Process Stats
The process stats data source allows you to get polled counters about the system and individual processes.
You can enable this source by setting process_stats_config and sys_stats_config in the DataSourceConfig.
The data that profetto
generates includes:
-
- /proc/meminfo
- /proc/vmstat
- /proc/stat
-
- /proc/<pid>/status
- /proc/<pid>/oom_score_adj
Depending on your device, OS version, and kernel, more events might be available. To learn more, refer to the config protos for sys_stats and process_stats.
Heapprofd
Heapprofd allows you to sample the causes of native memory use.
You can enable this source by setting heapprofd_config in the DataSourceConfig.
This produces ProfilePackets. These include the Java frames of the callstack.
Additional information on how to use heapprofd
can be found at
perfetto.dev.
Other sources
Depending on your device, OS version, and kernel, more data-sources might be available. To learn more, refer to the data source config protos.
Additional information about perfetto
can be found at
perfetto.dev.