1# PERFETTO(1) 2 3## NAME 4 5perfetto - capture traces 6 7## DESCRIPTION 8 9This section describes how to use the `perfetto` commandline binary to capture 10traces. Examples are given in terms of an Android device connected over ADB. 11 12`perfetto` has two modes for configuring the tracing session (i.e. what and how 13to collect): 14 15__lightweight mode__ 16: all config options are supplied as commandline flags, 17 but the available data sources are restricted to ftrace and atrace. This mode 18 is similar to 19 [`systrace`](https://developer.android.com/topic/performance/tracing/command-line). 20 21__normal mode__ 22: the configuration is specified in a protocol buffer. This allows for full 23 customisation of collected traces. 24 25 26## GENERAL OPTIONS 27 28The following table lists the available options when using `perfetto` in either 29mode. 30 31`-d`, `--background` 32: Perfetto immediately exits the command-line interface and continues 33 recording your trace in background. 34 35`-o`, `--out` _OUT_FILE_ 36: Specifies the desired path to the output trace file, or `-` for stdout. 37 `perfetto` writes the output to the file described in the flags above. 38 The output format compiles with the format defined in 39 [AOSP `trace.proto`](/protos/perfetto/trace/trace.proto). 40 41`--dropbox` _TAG_ 42: Uploads your trace via the 43 [DropBoxManager API](https://developer.android.com/reference/android/os/DropBoxManager.html) 44 using the tag you specify. Android only. 45 46`--no-guardrails` 47: Disables protections against excessive resource usage when enabling the 48 `--dropbox` flag during testing. 49 50 51`--reset-guardrails` 52: Resets the persistent state of the guardrails and exits (for testing). 53 54`--query` 55: Queries the service state and prints it as human-readable text. 56 57`--query-raw` 58: Similar to `--query`, but prints raw proto-encoded bytes of 59 `tracing_service_state.proto`. 60 61`-h`, `--help` 62: Prints out help text for the `perfetto` tool. 63 64 65## SIMPLE MODE 66 67For ease of use, the `perfetto` command includes support for a subset of 68configurations via command line arguments. On-device, these 69configurations behave equivalently to the same configurations provided 70by a *CONFIG_FILE* (see below). 71 72The general syntax for using `perfetto` in *simple mode* is as follows: 73 74``` 75 adb shell perfetto [ --time TIMESPEC ] [ --buffer SIZE ] [ --size SIZE ] 76 [ ATRACE_CAT | FTRACE_GROUP/FTRACE_NAME]... 77``` 78 79 80The following table lists the available options when using `perfetto` in 81*simple mode*. 82 83`-t`, `--time` _TIME[s|m|h]_ 84: Specifies the trace duration in seconds, minutes, or hours. 85 For example, `--time 1m` specifies a trace duration of 1 minute. 86 The default duration is 10 seconds. 87 88`-b`, `--buffer` _SIZE[mb|gb]_ 89: Specifies the ring buffer size in megabytes (mb) or gigabytes (gb). 90 The default parameter is `--buffer 32mb`. 91 92`-s`, `--size` _SIZE[mb|gb]_ 93: Specifies the max file size in megabytes (mb) or gigabytes (gb). 94 By default `perfetto` uses only in-memory ring-buffer. 95 96 97This is followed by a list of event specifiers: 98 99`ATRACE_CAT` 100: Specifies the atrace categories you want to record a trace for. 101 For example, the following command traces Window Manager using atrace: 102 `adb shell perfetto --out FILE wm`. To record other categories, see the 103 [list of atrace categories](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/native/cmds/atrace/atrace.cpp). 104 Note: Available categories are Android version dependent. 105 106`FTRACE_GROUP/FTRACE_NAME` 107: Specifies the ftrace events you want to record a trace for. 108 For example, the following command traces sched/sched_switch events: 109 `adb shell perfetto --out FILE sched/sched_switch` 110 111 112## NORMAL MODE 113 114The general syntax for using `perfetto` in *normal mode* is as follows: 115 116``` 117 adb shell perfetto [ --txt ] --config CONFIG_FILE 118``` 119 120The following table lists the available options when using `perfetto` in 121*normal* mode. 122 123`-c`, `--config` _CONFIG_FILE_ 124: Specifies the path to a configuration file. In normal mode, some 125 configurations may be encoded in a configuration protocol buffer. 126 This file must comply with the protocol buffer schema defined in AOSP 127 [`trace_config.proto`](/protos/perfetto/config/trace_config.proto). 128 You select and configure the data sources using the DataSourceConfig member 129 of the TraceConfig, as defined in AOSP 130 [`data_source_config.proto`](/protos/perfetto/config/data_source_config.proto). 131 132`--txt` 133: Instructs `perfetto` to parse the config file as pbtxt. This flag is 134 experimental, and it's not recommended that you enable it for production. 135