Android Perfetto Series 2: Capturing Perfetto Traces

Word count: 902Reading time: 5 min

 2024/05/21

The previous article Android Perfetto Series 1: Introduction to Perfetto introduced what Perfetto is. This article will provide a brief guide on how to capture Perfetto traces.

Perfetto Series Catalog
Main Content
1. Capturing via CLI (Recommended)
2. Capturing via Official Scripts
3. Using On-Device System Tracing
4. Using the Web Interface
Reference Documents

Paul Graham once said: “Either provide something most people want a little, or something a few people want a lot.“ Perfetto is exactly what a dedicated minority “wants a lot.” Let’s begin.

This series aims to provide a fresh perspective on Android system operation through Perfetto. It offers a unique angle to study App, Framework, and Linux internals. Through graphical tools like Perfetto, you may gain much deeper insights.

Perfetto Series Catalog

Main Content

The workflow for analyzing issues with Perfetto is identical to Systrace:

Capture the Perfetto trace file.
Open it in ui.perfetto.dev or analyze it via CLI.

This article introduces several capture methods. I strongly recommend the command-line approach for its flexibility and reliability.

1. Capturing via CLI (Recommended)

Basic Command - `adb shell perfetto`

For developers transition from Systrace, the CLI is very familiar. You can directly invoke /system/bin/perfetto on your Android device.

# 1. Start the trace
adb shell perfetto -o /data/misc/perfetto-traces/trace_file.perfetto-trace -t 20s \
 sched freq idle am wm gfx view binder_driver hal dalvik camera input res memory

# 2. Perform the target action (scrolling, launching, etc.)

# 3. Pull the trace to your machine
adb pull /data/misc/perfetto-traces/trace_file.perfetto-trace

This records a 20-second trace with specified data sources and saves it to the local device storage. You can then open the resulting file in the web UI.

Advanced: Using Config Files

Unlike Systrace, Perfetto can capture an enormous amount of data. Passing all tags via CLI every time is cumbersome. Instead, you can use a Config file and point Perfetto to it.

Android 12 and Newer

On Android 12+, you can store configs in /data/misc/perfetto-configs/.

1 2	adb push config.pbtx /data/misc/perfetto-configs/config.pbtx adb shell perfetto --txt -c /data/misc/perfetto-configs/config.pbtx -o /data/misc/perfetto-traces/trace.perfetto-trace

Older than Android 12

Due to SELinux restrictions on non-root devices, you must pass the config via standard input (stdin).

1 2	adb push config.pbtx /data/local/tmp/config.pbtx adb shell 'cat /data/local/tmp/config.pbtx \| perfetto -c - -o /data/misc/perfetto-traces/trace.perfetto-trace'

Where do I get a Config?

I recommend using the Record new trace wizard on the web UI to visually select your sources, then copy the result to a local file. This allows you to maintain different configs for different scenarios (e.g., startup vs. jank).

2. Using Official Scripts (Highly Recommended)

The Perfetto team provides a helper script record_android_trace that handles path management, pulls the file automatically upon completion, and opens it in your browser.

Linux and Mac:

curl -O https://raw.githubusercontent.com/google/perfetto/master/tools/record_android_trace
chmod u+x record_android_trace
./record_android_trace -o trace_file.perfetto-trace -t 10s -b 64mb \
  sched freq idle am wm gfx view binder_driver hal dalvik camera input res memory

Windows:

1
2
3

curl -O https://raw.githubusercontent.com/google/perfetto/master/tools/record_android_trace
python3 record_android_trace -o trace_file.perfetto-trace -t 10s -b 64mb \
  sched freq idle am wm gfx view binder_driver hal dalvik camera input res memory

You can also use -c to specify a config file with this script.

Script in Action

3. Using On-Device System Tracing

If you can’t connect to a PC, use the built-in System Tracing App in Developer Options.

Enable Developer Options: Tap “Build Number” 7 times in “About Phone.”
Open System Tracing: Find “System Tracing” in Developer Options.
Configure & Record: Set the duration and buffer size, then tap “Record Trace.” Use the notification toggle to stop recording.

Once finished, you can share or pull the file to a PC for analysis.

4. Using the Web Interface

Note: Capturing directly from the browser can be finicky due to ADB connection issues. I primarily use the web interface to generate configs rather than for the actual capture.

Visit ui.perfetto.dev/#!/record, select “Add ADB device,” and configure your data sources. Under Android apps, ensure “Atrace userspace annotations,” “Event log (logcat),” and “Frame timeline” are checked.

If you are debugging a debuggable process on a recent Android version, you can also enable Callstack sampling under Stack Samples to view function callstacks in the trace.

Transitioning from Web to CLI

After selecting your sources in the UI, click “Recording command” to see the generated Config. You can save this text to a .pbtx file for use with the CLI methods mentioned above.