Metadata-Version: 2.4
Name: perfetto-cli
Version: 0.2.0
Summary: CLI tool for Perfetto trace analysis - ANR, frame, CPU, memory, binder profiling
Project-URL: Homepage, https://github.com/SYKernel/perfetto-cli
Project-URL: Repository, https://github.com/SYKernel/perfetto-cli
Project-URL: Issues, https://github.com/SYKernel/perfetto-cli/issues
Project-URL: Changelog, https://github.com/SYKernel/perfetto-cli/blob/main/CHANGELOG.md
Author: SYKernel
License-Expression: MIT
License-File: LICENSE
Keywords: android,anr,binder,cpu,jank,memory,perfetto,performance,trace
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: perfetto>=0.14.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

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

[![CI](https://github.com/SYKernel/perfetto-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/SYKernel/perfetto-cli/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/perfetto-cli)](https://pypi.org/project/perfetto-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

English | [中文](README_zh.md)

---

## Installation

```bash
pip install perfetto-cli
```

Or run directly without installation via uvx:

```bash
uvx perfetto-cli --help
```

## Quick Start

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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](https://github.com/Textualize/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

```bash
# 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](https://click.palletsprojects.com/) >= 8.0 — CLI framework
- [rich](https://github.com/Textualize/rich) >= 13.0 — Rich terminal output
- [perfetto](https://pypi.org/project/perfetto/) >= 0.14.0 — Trace processing (includes trace_processor)
- `adb` — Required only for `trace` commands, must be in PATH

## License

[MIT](LICENSE)
