perfetto

perfetto is a tool that lets you collect performance information from Android devices via the Android Debug Bridge (ADB). Invoke the perfetto tool using the adb shell perfetto ... command. perfetto uses various sources to collect performance traces from your device, such as:

ftrace for information from the kernel
atrace for user-space annotation in services and apps
heapprofd for native memory usage information of services and apps

This page describes how to call perfetto and configure it to generate the desired output. For further information, refer to the perfetto documentation.

Syntax

This section describes how to use ADB to call perfetto for different modes 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, this mode offers an interface similar to systrace.
normal mode: gets its configuration in a protocol buffer and lets you leverage more of perfetto's functionality by using data sources different from atrace and ftrace.

General options

The following table lists the available options when using perfetto in either mode:

Table 1. List of available general perfetto tool options.

Option	Description
`--background \| -d`	`perfetto` immediately exits the command-line interface and continues recording your trace in background.
`--background-wait \| -D`	Like `--background`, but waits (up to 30s) for all data sources to start before exiting. Exit code is zero if a successful acknowledgement is received and non-zero otherwise (error or timeout).
`--alert-id`	ID of the alert that triggered this trace.
`--config-id`	ID of the triggering config.
`--config-uid`	UID of the app that registered the config.
`--subscription-id`	ID of the subscription that triggered this trace.
`--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 preceding flags. The output format compiles with the format defined in AOSP `trace.proto`. Note: You must specify the full pathname of the output file. Typically the files should be written to the `/data/misc/perfetto-traces` folder.
`--upload`	On completion, passes the trace to the package specified by the `IncidentReportConfig` message in the proto trace config.
`--no-guardrails`	Disables protections against excessive resource usage when enabling the `--upload` flag during testing.
`--reset-guardrails`	Resets the persistent state of the guardrails and exits for testing.
`--rsave-for-bugreport`	If a trace with `bugreport_score` > 0 is running, saves the trace into a file. Outputs the path when done.
`--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/* ]...
             --out FILE

The following table lists the available options when using perfetto in light mode:

Table 2. List of available perfetto tool options when using 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.
`--app \| -a`	Android (atrace) app name

These options are followed by a list of event specifiers:

Table 3. List of event specifiers for light mode.

Event Description

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

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 --out FILE

The following table lists the available options when using perfetto in normal mode:

Table 4. List of available perfetto tool options when using 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`. Select and configure the data sources using the `DataSourceConfig` member of the `TraceConfig`, as defined in AOSP `data_source_config.proto`.
`--txt`	Instructs `perfetto` to parse the config file as `pbtxt`. This flag is intended for local testing only, 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.

Enable this source by setting ftrace_config in the DataSourceConfig.

The events that can be enabled include:

Scheduling activity:
- 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:
- ext4
- f2fs
- block
atrace events

Depending on your device, OS version, or 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.

Enable this source by setting process_stats_config and sys_stats_config in the DataSourceConfig.

The data that perfetto generates includes:

System-wide
- /proc/meminfo
- /proc/vmstat
- /proc/stat
Per process
- /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 lets you sample the causes of native memory use.

Enable this source by setting heapprofd_config in the DataSourceConfig. This setting produces ProfilePackets, including 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.