[!IMPORTANT] Scope: This guide is strictly for recording traces on Android devices. For Linux, read recording_linux_traces.md; for other platforms (macOS, Chrome), please refer to the platform-specific documentation on perfetto.dev/docs.
Rather than running raw adb commands, you should use the official Perfetto helper scripts. They automatically handle pushing configurations, starting the tracing daemons, pulling the trace file, and optionally opening it in the browser.
Ensure Developer options and USB debugging are enabled, and your device is connected via USB before starting.
Since these tools need to work across different environments, download them directly from the official Perfetto repository:
# Java Heap Dump (ART) curl -O https://raw.githubusercontent.com/google/perfetto/main/tools/java_heap_dump chmod +x java_heap_dump # Native Heap Profiling (heapprofd) curl -O https://raw.githubusercontent.com/google/perfetto/main/tools/heap_profile chmod +x heap_profile # CPU Stack Sampling (traced_perf) curl -O https://raw.githubusercontent.com/google/perfetto/main/tools/cpu_profile chmod +x cpu_profile # General Tracing (Ftrace, ATrace, custom configs) curl -O https://raw.githubusercontent.com/google/perfetto/main/tools/record_android_trace chmod +x record_android_trace
Use these tools to analyze memory leaks, object retention, C/C++ allocations, or system-wide memory counters.
Capture a snapshot of all Java objects in a process to investigate memory leaks.
# Trigger a Java heap dump for a specific app ./java_heap_dump -n YOUR_APP_PACKAGE_NAME -o ./heap_dump.perfetto-trace
Track C/C++ memory allocations (malloc/free) to find native leaks.
# Profile native allocations for a specific app ./heap_profile -n YOUR_APP_PACKAGE_NAME # Profile with custom sampling interval (default is 4096 bytes) ./heap_profile -n YOUR_APP_PACKAGE_NAME -i 2048
Track RSS, Swap, and process stats over time.
Note: To record memory counters, you must use a custom config via record_android_trace (see Section 4).
Identify CPU hot spots in C/C++ or Rust code by periodically sampling callstacks.
# Profile CPU usage by sampling callstacks at 100Hz (default) for 10 seconds ./cpu_profile -n YOUR_APP_PACKAGE_NAME -d 10000 # Profile at a custom frequency (e.g., 200Hz) ./cpu_profile -n YOUR_APP_PACKAGE_NAME -f 200
Investigate jank, slow transitions, CPU scheduling, and system calls.
You can specify duration, buffer size, and categories directly on the command line:
# Record scheduling, frequency, and window manager events for 5 seconds ./record_android_trace -t 5s -b 32mb sched gfx wm -a YOUR_APP_PACKAGE_NAME
Common categories: sched (CPU scheduling), freq (CPU frequency), gfx (Graphics), am (Activity Manager), wm (Window Manager), view (View System).
If you need a custom mixture of data sources (e.g., combining Java heap dumps with ftrace), or control the command-line flags don't offer (ring buffers, long traces, per-counter polling), synthesize a config:
Read the config reference: trace_config_reference.md explains the config shape and every common data source, and points to ready-made exemplar configs in $SKILL_ROOT/infra-references/example-configs/ that you can start from and merge. For exotic data sources not covered there, draft from the Perfetto Data Sources Documentation.
Save the Config: Write the synthesized text configuration to a local file (e.g., config.pftxt).
Execute the Trace: Run the trace using the general recorder script record_android_trace (the other specialized scripts will not work for custom configs):
./record_android_trace -c config.pftxt -o ./my_trace.perfetto-trace
If the config has a typo, this fails fast with a parse error naming the bad field — fix the config and retry.