Metadata-Version: 2.4
Name: androidperf
Version: 0.1.2
Summary: ADB-based Android performance metric recorder with live TUI and HTML report
Project-URL: Homepage, https://github.com/jitinsharma/androidperf
Project-URL: Repository, https://github.com/jitinsharma/androidperf
Project-URL: Issues, https://github.com/jitinsharma/androidperf/issues
Project-URL: Changelog, https://github.com/jitinsharma/androidperf/blob/main/CHANGELOG.md
Author-email: Jitin Sharma <jitins2892@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Jitin Sharma
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: adb,android,cli,fps,performance,profiling
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: adbutils>=2.8.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pandas>=2.2.0
Requires-Dist: plotly>=5.22.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# androidperf

A CLI that records Android app runtime performance over ADB — CPU, RAM,
network, FPS/jank, battery, thermal, and screen transitions — draws a live
terminal dashboard while it runs, and drops a self-contained HTML report at
the end.

```
┌── androidperf · com.example.app · Pixel 7 (sdk 34)     samples 42  elapsed 00:41 ──┐
│ screen HomeActivity     battery 87% charging 31°C      thermal moderate skin 35°C  │
├──── CPU ────┬── Memory ─────────┬──── Network ────┬──── FPS ────┐
│             │                   │                 │             │
│   19.2 %    │  Total PSS 199 MB │   ↓ rx 5 KB/s   │  fps  58.2  │
│    ▁▂▄▆█    │  Java       39 MB │   ↑ tx 2 KB/s   │  jank 3.1 % │
│             │  Native     44 MB │                 │  p95    18  │
│ per-process │  Graphics   20 MB │       ▁▂        │     █▆▄▂▁   │
│     CPU     │         ▁▂        │       ▁▂        │             │
└─────────────┴───────────────────┴─────────────────┴─────────────┘
                             Ctrl+C to stop
```

## Requirements

| | |
|---|---|
| **Python** | 3.11 or newer |
| **adb** | Android Platform Tools on `$PATH`. macOS: `brew install --cask android-platform-tools`. Debian/Ubuntu: `sudo apt install adb`. Windows/other: <https://developer.android.com/tools/releases/platform-tools>. Verify with `adb version`. |
| **Android device** | Physical device or emulator running **Android 7.0 (SDK 24) or newer** — `dumpsys gfxinfo framestats` needs SDK 24+. |
| **USB debugging** | Enabled in Developer Options, and the host authorized (`adb devices` shows the serial as `device`, not `unauthorized`). |
| **Python deps** | Installed automatically: `adbutils`, `typer`, `rich`, `jinja2`, `plotly`, `pandas`. |

`adb` is **not** a Python package — it's a standalone binary. If `androidperf devices` says "command not found", that's the missing piece.

## Install

```bash
pipx install androidperf          # recommended — isolated, globally available
# or
pip install androidperf           # into the current environment
```

From source (until the package is on PyPI, or if you want to hack on it):

```bash
git clone https://github.com/jitinsharma/androidperf.git
cd androidperf

# Option A — globally available, isolated venv managed by pipx:
pipx install .
pipx install --editable .          # if you plan to edit the code

# Option B — a regular venv with the dev extras (pytest, ruff):
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

## Quickstart

```bash
# 1. See connected devices
androidperf devices

# 2. Find the package you want to profile
androidperf packages --filter com.android

# 3. Search app and record
androidperf record

# 3. Launch the app and record for 60s at 1s cadence
androidperf record --package com.android.settings --interval 1 --duration 60

```

If `--package` is omitted, `record` drops into an interactive prompt: type a
substring, pick a number.

Attach to an already-running app instead of launching it:

```bash
androidperf record --package com.example.app --no-launch
```

Stop early with `Ctrl+C` — the JSON and HTML are still written with whatever
samples were collected. After the session ends, a stat-card panel prints in
the terminal with the same summary numbers that appear in the HTML report.

Each run writes to `runs/<timestamp>-<pkg>/`:

- `samples.json` — raw time-series data, easy to diff or re-plot
- `report.html` — single self-contained file, opens offline

## What gets measured

| Metric | Source |
|---|---|
| CPU % (per-core summed) | `top -n 1 -b -p <pid>` |
| RAM: PSS / Java / Native / Graphics / Code / Stack | `dumpsys meminfo <package>` |
| Network rx/tx (per-tick deltas) | `/proc/net/xt_qtaguid/stats` (falls back to `dumpsys netstats --uid=<uid>` on Android 10+) |
| Frame rendering rate, jank %, frame p50/p90/p95/p99 | `dumpsys gfxinfo <package>` (window read directly from `Uptime` − `Stats since` for accuracy) |
| Battery: level, temp, voltage, status | `dumpsys battery` |
| Thermal: status, skin/cpu/gpu/battery °C | `dumpsys thermalservice` |
| Activity transitions | `dumpsys activity activities` |
| Active fragment (top-level + deepest visible child) | `dumpsys activity <component>` — AndroidX FragmentManager apps only |

CPU is reported as `top`'s raw `%CPU` — i.e., summed across cores. 200% means
the process is using two cores worth of time. This is the same convention
used by Android Studio's CPU profiler.

A note on FPS: Android UI rendering is **demand-driven**. The app submits a
frame only when something on screen changes (animation tick, scroll, view
invalidation), so `frames/sec` goes to zero on a static screen — that's
correct, not a bug. `androidperf` reports it as an *activity trace* and
leads the smoothness summary with **jank %** and **p95 frame time**, which
are the metrics that actually correlate with perceived smoothness.

## HTML report

The report opens with a compact **screen-timeline swim-lane** (Activity row +
Fragment row) showing colored segments across the session — one glance tells
you what was on screen when. Below that, the metric charts have a unified
hover that includes the active activity + fragment at any timestamp, so you
can correlate spikes with user navigation without leaving the chart. The
report also includes:

- Summary stat cards (averages, peaks, network totals, battery delta).
- Interactive Plotly charts — zoom, pan, hover tooltips, toggle traces in the
  legend. No network required to view the report; `plotly.js` is inlined.

## Commands

| Command | Purpose |
|---|---|
| `androidperf devices` | List connected ADB devices. |
| `androidperf packages [--filter X] [--serial S] [--limit N]` | List installed packages. |
| `androidperf record --package PKG [...]` | Record a session; write JSON + HTML. |
| `androidperf report SAMPLES_JSON` | Regenerate HTML from an existing run. |
| `androidperf version` | Print installed version. |

## Development

```bash
pytest -q         # parser + report tests (no device required)
ruff check src    # lint
```

Parsers live under `src/androidperf/collectors/` and are tested against
captured command output in `tests/fixtures/`. When you hit a device whose
output differs, add a fixture file + an assertion and the parser can be
updated against it without any device plugged in.

## Layout

```
src/androidperf/
├── cli.py                # Typer entry point
├── device.py             # adb detection, package list, app launch
├── session.py            # polling loop, signal handling, JSON writer
├── summary.py            # shared summary-card computation (HTML + terminal)
├── collectors/           # cpu, memory, network, fps, battery, thermal, activity, fragments
├── ui/                   # live.py (Live dashboard) + summary.py (end-of-run panel)
└── report/               # Jinja2 + Plotly → self-contained HTML
```

See [`plan/`](./plan) for architecture and future-direction docs.

## License

MIT.
