1# Perfetto CLI 2 3This section describes how to use the `perfetto` commandline binary to capture 4traces. Examples are given in terms of an Android device connected over ADB. 5 6`perfetto` has two modes for configuring the tracing session (i.e. what and how 7to collect): 8 9* __lightweight mode__: all config options are supplied as commandline flags, 10 but the available data sources are restricted to ftrace and atrace. This mode 11 is similar to 12 [`systrace`](https://developer.android.com/topic/performance/tracing/command-line). 13* __normal mode__: the configuration is specified in a protocol buffer. This 14 allows for full customisation of collected traces. 15 16 17## General options 18 19The following table lists the available options when using `perfetto` in either 20mode. 21 22|Option|Description| 23|---|---| 24| `--background \| -d` |Perfetto immediately exits the command-line interface and continues recording your trace in background.| 25|`--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`](/protos/perfetto/trace/trace.proto).| 26|`--dropbox TAG`|Uploads your trace via the [DropBoxManager API](https://developer.android.com/reference/android/os/DropBoxManager.html) using the tag you specify.| 27|`--no-guardrails`|Disables protections against excessive resource usage when enabling the `--dropbox` flag during testing.| 28|`--reset-guardrails`|Resets the persistent state of the guardrails and exits (for testing).| 29|`--query`|Queries the service state and prints it as human-readable text.| 30|`--query-raw`|Similar to `--query`, but prints raw proto-encoded bytes of `tracing_service_state.proto`.| 31|`--help \| -h`|Prints out help text for the `perfetto` tool.| 32 33 34## Lightweight mode 35 36The general syntax for using `perfetto` in *lightweight mode* is as follows: 37 38<pre class="none"> 39 adb shell perfetto [ --time <var>TIMESPEC</var> ] [ --buffer <var>SIZE</var> ] [ --size <var>SIZE</var> ] 40 [ <var>ATRACE_CAT</var> | <var>FTRACE_GROUP/FTRACE_NAME</var>]... 41</pre> 42 43 44The following table lists the available options when using `perfetto` in 45*lightweight mode*. 46 47|Option|Description| 48|--- |--- | 49|`--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.| 50|`--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`.| 51|`--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.| 52 53 54This is followed by a list of event specifiers: 55 56|Event|Description| 57|--- |--- | 58|`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](https://android.googlesource.com/platform/frameworks/native/+/refs/tags/android-q-preview-5/cmds/atrace/atrace.cpp#100).| 59|`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`| 60 61 62## Normal mode 63 64The general syntax for using `perfetto` in *normal mode* is as follows: 65 66<pre class="none"> 67 adb shell perfetto [ --txt ] --config <var>CONFIG_FILE</var> 68</pre> 69 70The following table lists the available options when using `perfetto` in *normal* mode. 71 72|Option|Description| 73|--- |--- | 74|`--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`](/protos/perfetto/config/data_source_config.proto). You select and configure the data sources using the DataSourceConfig member of the TraceConfig, as defined in [AOSP `data_source_config.proto`](/protos/perfetto/config/data_source_config.proto).| 75|`--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.| 76