docs/reference/perfetto-cli.md - third_party/perfetto - Git at Google


            
            # PERFETTO(1)


            ## NAME


            perfetto - 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`](https://developer.android.com/topic/performance/tracing/command-line).


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

            
                 Writes `0` on 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.

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


            `--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 `--clone` or `--clone-by-name`. Disables

            
                 `trace_filter` on the cloned session.


            `--add-attribute` _key[=value]_

            
            :    Adds a [trace attribute](/protos/perfetto/common/trace_attributes.proto),

            
                 a key/value pair describing the trace. If `=value` is omitted, the value

            
                 is an empty string. Attributes appear in Trace Processor's `metadata`

            
                 table as `trace_attribute.<key>` rows.


            `--version`

            
            :    Prints the `perfetto` version string and exits.


            `--dropbox` _TAG_

            
            :    **Deprecated.** Uploads your trace via the

            
                 [DropBoxManager API](https://developer.android.com/reference/android/os/DropBoxManager.html)

            
                 using the tag you specify. Android only. Use `--upload` instead.


            `--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 > 0` is 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 `--query` output (for example category lists).

            
                 Can only be used with `--query`.


            `--query-raw`

            
            :     Similar to `--query`, but prints raw proto-encoded bytes of

            
                  `tracing_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:

            
                  `0` yes, `2` no, `1` error.


            `-h`,  `--help`

            
            :     Prints out help text for the `perfetto` tool.


            ## 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 1m` specifies 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 `perfetto` uses 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](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/native/cmds/atrace/atrace.cpp).

            
                 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`](/protos/perfetto/config/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`](/protos/perfetto/config/data_source_config.proto).

            
                 Use `-` to read config bytes from stdin.


            `--txt`

            
            :    Instructs `perfetto` to parse the config file as pbtxt. This flag is

            
                 not a stable API and is not recommended for production.
	# PERFETTO(1)

	## NAME

	perfetto - 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`](https://developer.android.com/topic/performance/tracing/command-line).

	__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.
	Writes `0` on 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.
	`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).

	`--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 `--clone` or `--clone-by-name`. Disables
	`trace_filter` on the cloned session.

	`--add-attribute` _key[=value]_
	: Adds a [trace attribute](/protos/perfetto/common/trace_attributes.proto),
	a key/value pair describing the trace. If `=value` is omitted, the value
	is an empty string. Attributes appear in Trace Processor's `metadata`
	table as `trace_attribute.<key>` rows.

	`--version`
	: Prints the `perfetto` version string and exits.

	`--dropbox` _TAG_
	: Deprecated. Uploads your trace via the
	[DropBoxManager API](https://developer.android.com/reference/android/os/DropBoxManager.html)
	using the tag you specify. Android only. Use `--upload` instead.

	`--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 > 0` is 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 `--query` output (for example category lists).
	Can only be used with `--query`.

	`--query-raw`
	: Similar to `--query`, but prints raw proto-encoded bytes of
	`tracing_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:
	`0` yes, `2` no, `1` error.

	`-h`, `--help`
	: Prints out help text for the `perfetto` tool.


	## 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 1m` specifies 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 `perfetto` uses 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](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/native/cmds/atrace/atrace.cpp).
	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`](/protos/perfetto/config/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`](/protos/perfetto/config/data_source_config.proto).
	Use `-` to read config bytes from stdin.

	`--txt`
	: Instructs `perfetto` to parse the config file as pbtxt. This flag is
	not a stable API and is not recommended for production.