PERFETTO(1)

📦
version 56.0 · 3 versions
, in ubuntu stonking

💖 PERFETTO(1) 💖 — the perfetto girlies' guide to capturing traces

okay so bestie, welcome to the perfetto manual page (that's the General Commands Manual one, mwah). pull up a chair, grab a strawberry 🍓, and let's learn how to capture traces together. no cap, this one's a banger.

✨ NAME ✨

perfetto — capture traces 💅

🌸 DESCRIPTION 🌸

this section is literally all about how to use the perfetto commandline binary to capture traces. all the examples are given in terms of an Android device connected over ADB, iykyk.

so perfetto has two modes for configuring the tracing session (aka what you're collecting and how you're collecting it):

  • lightweight mode — every config option gets supplied as commandline flags, but the available data sources are restricted to ftrace and atrace. this mode is similar to systrace. cute and quick 🎀
  • normal mode — the configuration is specified in a protocol buffer. this allows for full customisation of collected traces. main character energy fr fr 👑

💅 GENERAL OPTIONS 💅

the following table lists all the available options when you're using perfetto in either mode. slay.

  • -d, --background — perfetto immediately exits the command-line interface and continues recording your trace in background. bye bestie, still recording tho 🫶
  • -D, --background-wait — like --background, but it waits (up to 30s) for all data sources to be started before exiting. patient queen ✨
  • --notify-fd FD — like --background-wait, but instead of daemonizing and waiting before exiting, it 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. 📁
  • --no-clobber — do not overwrite an existing output file. protect the babies 🙈
  • --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-note key[=value] — adds a user note to the trace config. if =value is omitted, value is an empty string. ✍️
  • --version — prints the perfetto version string and exits.
  • --dropbox TAG — deprecated. uploads your trace via the DropBoxManager API using the tag you specify. Android only. use --upload instead. (we don't gatekeep, we just move on 💅)
  • --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, it 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. the whole squad, collected 🌈
  • --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. (yes bestie, three whole numbers, memorize them 💅)
  • -h, --help — prints out help text for the perfetto tool. when in doubt, ask for help, that's growth 💖

🎀 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). love that for us.

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 you're 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. 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 you're 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 AOSP 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. ⚠️
ngl the --txt thing is giving "not for prod" vibes. treat it accordingly bestie 💜

and that's the whole page!! ty for reading the PERFETTO(1) manual, you ate that fr fr 🍓💅✨

~ fin (the General Commands Manual version, PERFETTO(1)) ~

📦 where this page comes from