perfetto

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 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.

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.
--upload On completion pass 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).
--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.

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

You can 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:

  • ATrace 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 perfetto generates includes:

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.