perfetto-cli

A CLI tool for Android Perfetto trace analysis — ANR detection, frame jank, CPU profiling, memory leak detection, binder transactions, and raw SQL queries, all from the terminal.

English | 中文 | Documentation

---

Installation

pip install perfetto-cli

Or run directly without installation via uvx:

uvx perfetto-cli --help

AI Tool Integration (Optional)

perfetto-cli provides a skills system that integrates with AI coding assistants (Claude Code, Cursor, Codex, Gemini CLI, OpenCode). Once installed, AI tools can automatically understand and use perfetto-cli for trace analysis.

# Interactive install — detects your AI tools and guides you through setup
perfetto-cli skills install

# Or install all skills to all detected tools at once
perfetto-cli skills install --all --target all --scope global

After installation, you can ask your AI assistant naturally:

> My app feels laggy, analyze this trace: ./app-trace.perfetto-trace

The AI will automatically run the appropriate perfetto-cli commands and interpret the results. See AI-Powered Usage for details.

Quick Start

# Detect ANR events
perfetto-cli -t trace.perfetto-trace -p com.example.app anr detect

# Detect frame jank
perfetto-cli -t trace.perfetto-trace -p com.example.app frame jank

# View CPU utilization
perfetto-cli -t trace.perfetto-trace -p com.example.app cpu utilization

# Capture trace from device (requires adb)
perfetto-cli trace start
perfetto-cli trace stop

Global Options

Option	Description
-t, --trace <path>	Trace file path (required)
-p, --process <name>	Process name filter
-f, --format <type>	Output format: json / table / text (default: text)
-v, --verbose	Verbose output
--tp-path <path>	Custom trace_processor binary path
--version	Show version

Commands

ANR Analysis

Detect ANR (Application Not Responding) events and identify root causes.

# Detect ANR events with severity classification
perfetto-cli -t trace.perfetto-trace -p com.example.app anr detect

# Filter by minimum duration
perfetto-cli -t trace.perfetto-trace -p com.example.app anr detect --min-duration 3000

# Multi-signal root cause analysis (requires ANR timestamp)
perfetto-cli -t trace.perfetto-trace -p com.example.app anr root-cause --anr-timestamp 5000

Frame Performance

Analyze frame rendering performance and detect jank.

# Detect janky frames (SMOOTH / JANK / BIG_JANK / HUGE_JANK)
perfetto-cli -t trace.perfetto-trace -p com.example.app frame jank

# Custom jank threshold (default: 16ms)
perfetto-cli -t trace.perfetto-trace -p com.example.app frame jank --threshold 16

# Frame performance summary with rating
perfetto-cli -t trace.perfetto-trace -p com.example.app frame summary

CPU Analysis

Thread-level CPU utilization, hotspot detection, and contention analysis.

# Per-thread CPU utilization
perfetto-cli -t trace.perfetto-trace -p com.example.app cpu utilization

# Include CPU frequency (DVFS) info
perfetto-cli -t trace.perfetto-trace -p com.example.app cpu utilization --include-frequency

# Main thread hotspot slices (top-N)
perfetto-cli -t trace.perfetto-trace -p com.example.app cpu hotspots --limit 30

# Thread contention analysis
perfetto-cli -t trace.perfetto-trace -p com.example.app cpu contention

Memory Analysis

Memory leak detection and heap analysis.

# Detect memory leaks via RSS growth trend
perfetto-cli -t trace.perfetto-trace -p com.example.app memory leak

# Custom growth threshold (default: 5 MB/min)
perfetto-cli -t trace.perfetto-trace -p com.example.app memory leak --growth-threshold 10

# Heap dominator tree analysis
perfetto-cli -t trace.perfetto-trace -p com.example.app memory heap

Binder Analysis

Binder IPC transaction performance profiling.

# Binder transaction analysis
perfetto-cli -t trace.perfetto-trace -p com.example.app binder profile

# Filter by minimum latency (default: 10ms)
perfetto-cli -t trace.perfetto-trace -p com.example.app binder profile --min-latency 20

# Group by AIDL interface
perfetto-cli -t trace.perfetto-trace -p com.example.app binder profile --group-by aidl

SQL Queries

Execute raw PerfettoSQL queries and search trace data.

# Execute SQL query
perfetto-cli -t trace.perfetto-trace query sql --query "SELECT * FROM slice LIMIT 10"

# Execute SQL from file
perfetto-cli -t trace.perfetto-trace query sql --file query.sql

# Search slices (supports contains/exact/glob)
perfetto-cli -t trace.perfetto-trace query find-slices --pattern "Choreographer"

Trace Capture

Capture Perfetto traces from device via adb.

# Start capture with default config (10s)
perfetto-cli trace start

# Custom duration
perfetto-cli trace start --duration 30s

# Custom buffer size (default: 32MB)
perfetto-cli trace start --buffer-size 64mb

# Stop capture and pull trace file
perfetto-cli trace stop

# One-shot capture (start → wait → stop → pull)
perfetto-cli trace run --duration 15s -o ./traces

Output Formats

Use -f, --format to specify output format:

• text (default): Human-friendly colorized terminal output via Rich
• table: ASCII table output, suitable for aligned data viewing
• json: Machine-readable JSON for scripting and piping

Command Reference

Domain	Command	Description
anr	detect	ANR event detection with severity
anr	root-cause	Multi-signal ANR root cause analysis
frame	jank	Frame jank detection
frame	summary	Frame performance summary & rating
cpu	utilization	Thread-level CPU utilization
cpu	hotspots	Main thread hotspot slices
cpu	contention	Thread contention analysis
memory	leak	RSS-based memory leak detection
memory	heap	Heap dominator tree analysis
binder	profile	Binder transaction profiling
query	sql	Execute raw PerfettoSQL
query	find-slices	Search slices by pattern
query	slice-info	Get slice details
trace	start	Start device trace capture
trace	stop	Stop capture and pull trace
trace	run	One-shot capture

Development

# Clone the repo
git clone https://github.com/SYKernel/perfetto-cli.git
cd perfetto-cli

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

Dependencies

• Python >= 3.10
• click >= 8.0 — CLI framework
• rich >= 13.0 — Rich terminal output
• perfetto >= 0.14.0 — Trace processing (includes trace_processor)
• adb — Required only for trace commands, must be in PATH

License

MIT