perfetto - Man Page
capture traces
Description
This section describes how to use the perfetto commandline binary to capture traces. Examples are given in terms of an Android device connected over ADB.
perfetto has two modes for configuring the tracing session (i.e. what and how to collect):
- lightweight mode
all config options are supplied as commandline flags, but the available data sources are restricted to ftrace and atrace. This mode is similar to
systrace\c .- normal mode
the configuration is specified in a protocol buffer. This allows for full customisation of collected traces.
General Options
The following table lists the available options when using perfetto in either mode.
- -d, --background
Perfetto immediately exits the command-line interface and continues recording your trace in background.
- -D, --background-wait
Like
--background, but waits (up to 30s) for all data sources to be started before exiting.- --notify-fd FD
Like
--background-wait, but instead of daemonizing and waiting before exiting, writes one status byte and closes the given file descriptor. Writes0on success, non-zero on timeout/error. Not supported on Windows.- -o, --out OUT_FILE
Specifies the desired path to the output trace file, or
-for stdout.perfettowrites the output to the file described in the flags above. The output format compiles with the format defined in AOSPtrace.proto.- --no-clobber
Do not overwrite an existing output file.
- --clone TSID
Creates a read-only clone of an existing tracing session identified by session id (see
--query).- --clone-by-name NAME
Creates a read-only clone of an existing tracing session identified by
unique_session_name.- --clone-for-bugreport
Can only be used with
--cloneor--clone-by-name. Disablestrace_filteron the cloned session.- --add-note key[=value]
Adds a user note to the trace config. If
=valueis omitted, value is an empty string.- --version
Prints the
perfettoversion string and exits.- --dropbox TAG
Deprecated. Uploads your trace via the DropBoxManager API\c using the tag you specify. Android only. Use
--uploadinstead.- --upload
Uploads trace output to Android framework reporting paths configured in
TraceConfig(android_report_config). Android only.- --alert-id ID
Statsd metadata. ID of the alert that triggered this trace.
- --config-id ID
Statsd metadata. ID of the triggering config.
- --config-uid UID
Statsd metadata. UID of app which registered the triggering config.
- --subscription-id ID
Statsd metadata. ID of the subscription that triggered this trace.
- --save-for-bugreport
If a trace with
bugreport_score > 0is running, saves it into a file and outputs the path when done.- --save-all-for-bugreport
Clones all eligible bugreport sessions and saves them into bugreport output files.
- --no-guardrails
Disables protections against excessive resource usage when using
--upload(testing only).- --reset-guardrails
Compatibility option. Guardrails no longer exist in
perfetto_cmd; this option remains for backwards compatibility.- --query
Queries the service state and prints it as human-readable text.
- --long
Expands some fields in
--queryoutput (for example category lists). Can only be used with--query.- --query-raw
Similar to
--query, but prints raw proto-encoded bytes oftracing_service_state.proto.- --detach KEY
Detach from tracing session using the given key.
- --attach KEY
Re-attach to a detached tracing session using the given key.
- --stop
Stop tracing once re-attached. Supported only with
--attach.- --is_detached KEY
Checks whether the session can be re-attached. Exit code semantics:
0yes,2no,1error.- -h, --help
Prints out help text for the
perfettotool.
Simple Mode
For ease of use, the perfetto command includes support for a subset of configurations via command line arguments. On-device, these configurations behave equivalently to the same configurations provided by a CONFIG_FILE (see below).
The general syntax for using perfetto in simple mode is as follows:
adb shell perfetto [ --time TIMESPEC ] [ --buffer SIZE ] [ --size SIZE ]
[ --app APP_NAME ]
[ ATRACE_CAT | FTRACE_GROUP/FTRACE_NAME]...The following table lists the available options when using perfetto in simple mode.
- -t, --time TIME[s|m|h]
Specifies the trace duration in seconds, minutes, or hours. For example,
--time 1mspecifies a trace duration of 1 minute. The default duration is 10 seconds.- -b, --buffer SIZE[mb|gb]
Specifies the ring buffer size in megabytes (mb) or gigabytes (gb). The default parameter is
--buffer 32mb.- -s, --size SIZE[mb|gb]
Specifies the max file size in megabytes (mb) or gigabytes (gb). By default
perfettouses only in-memory ring-buffer.- -a, --app APP_NAME
Specifies an Android app name for atrace app-level tracing.
This is followed by a list of event specifiers:
- 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 the list of atrace categories\c . Note: Available categories are Android version dependent.- 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
The following table lists the available options when using perfetto in normal mode.
- -c, --config 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 AOSPdata_source_config.proto. Use-to read config bytes from stdin.- --txt
Instructs
perfettoto parse the config file as pbtxt. This flag is not a stable API and is not recommended for production.