`perfetto` is a tool that lets you collect performance information from
Android devices via the
[Android Debug Bridge (ADB)](https://developer.android.com/studio/command-line/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](https://perfetto.dev/docs).


## Android skills

[View on GitHub](https://github.com/android/skills/tree/main/profilers/android-profiler/analysis/workflows)

### Perfetto trace analysis

Use an [Android skill](https://developer.android.com/tools/agents/android-skills) to diagnose Android performance issues with the `perfetto` tool. To install the relevant skills from the [Android CLI](https://developer.android.com/tools/agents/android-cli), run:

    android skills add [perfetto-trace-analyzer|perfetto-sql]

<br />

## 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`](https://developer.android.com/topic/performance/tracing/command-line).
- **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`](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/trace/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 |
|---|---|
| <var translate="no">ATRACE_CAT</var> | 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](https://android.googlesource.com/platform/frameworks/native/+/refs/tags/android-q-preview-5/cmds/atrace/atrace.cpp#100). |
| <var translate="no"> FTRACE_GROUP/FTRACE_NAME</var> | 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`](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/config/trace_config.proto). Select and configure the data sources using the `DataSourceConfig` member of the `TraceConfig`, as defined in [AOSP `data_source_config.proto`](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/config/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 lets `perfetto` get events from the kernel.

Enable this source by setting
[`ftrace_config`](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/config/ftrace/ftrace_config.proto)
in the DataSourceConfig.

The events that can be enabled include:

- [Scheduling activity](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/trace/ftrace/sched.proto):

  - `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`](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/trace/ftrace/ext4.proto)
  - [`f2fs`](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/trace/ftrace/f2fs.proto)
  - [`block`](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/trace/ftrace/block.proto)
- [`atrace` events](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/trace/ftrace/print.proto)

Depending on your device, OS version, or kernel, more events might be
available. For more information, refer to the [config protos](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/trace/ftrace/).

### Process stats

The process stats data source lets you get polled counters about the
system and individual processes.

Enable this source by setting [`process_stats_config`](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/config/process_stats/process_stats_config.proto)
and [`sys_stats_config`](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/config/sys_stats/sys_stats_config.proto)
in the DataSourceConfig.

The data that `perfetto` generates includes:

- [System-wide](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/trace/sys_stats/sys_stats.proto)

  - `/proc/meminfo`
  - `/proc/vmstat`
  - `/proc/stat`
- [Per process](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/trace/ps/process_stats.proto)

  - `/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`](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/config/sys_stats/sys_stats_config.proto)
and [`process_stats`](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/config/process_stats/process_stats_config.proto).

### `heapprofd`

`heapprofd` lets you sample the causes of native memory use.

Enable this source by setting [`heapprofd_config`](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/config/profiling/heapprofd_config.proto)
in the DataSourceConfig. This setting produces [`ProfilePackets`](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/trace/profiling/profile_packet.proto),
including the Java frames of the callstack.

Additional information on how to use `heapprofd` can be found at
[`perfetto.dev`](https://docs.perfetto.dev/#heapprofd).

### 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](https://android.googlesource.com/platform/external/perfetto/+/refs/tags/android-q-preview-5/protos/perfetto/config/data_source_config.proto).

Additional information about `perfetto` can be found at
[perfetto.dev](https://perfetto.dev).