PerfSight

PerfSight is a local Android performance watcher for endurance runs. It samples app CPU, total PSS, memory composition, leak signals, heap dumps, and Web UI live state from adb.

Quick Start

Install

npm install -g @sireai/perfsight

Or run without installing:

npx @sireai/perfsight text com.mi.car.mobile

Run

Text mode:

perfsight text com.mi.car.mobile

Web mode:

perfsight web com.mi.car.mobile

Enable leak capture:

perfsight text com.mi.car.mobile --enable-leak-capture
perfsight web com.mi.car.mobile --enable-leak-capture

Start from a clean artifact set for the current package:

perfsight text com.mi.car.mobile --output-dir ./data --reset-output-dir

Show periodic CPU/PSS sample lines in text mode:

perfsight text com.mi.car.mobile --enable-leak-capture --show-samples

When text mode runs in an interactive terminal, press T to start/stop a Perfetto trace, C for a CPU profile, D for a manual HPROF dump, H for status, or Q to stop safely. These controls are disabled for redirected output and CI runs.

Automation Capture

Use one option for unattended artifact capture. Each command waits for a running app process, saves its artifact, then exits:

perfsight text com.example.app --capture memory --output-dir ./artifacts
perfsight text com.example.app --capture cpu --duration 30 --output-dir ./artifacts
perfsight text com.example.app --capture trace --duration 15 --output-dir ./artifacts

memory writes an HPROF and requires a debuggable app or rooted device. cpu uses device simpleperf and verifies availability for the running app with a short probe. trace records a device-native Perfetto app-responsiveness trace. --duration defaults to 30 seconds for CPU and Perfetto captures. --capture is a one-shot operation and cannot be combined with --enable-leak-capture.

APK Artifact Analysis

Analyze a local APK without adb, Android SDK, or Java:

perfsight artifact inspect app-release.apk
perfsight artifact inspect app-release.apk --open
perfsight artifact inspect app-release.apk --mode web
perfsight artifact compare previous.apk current.apk
perfsight artifact compare previous.apk current.apk --open
perfsight artifact compare previous.apk current.apk --mode web

Artifact analysis reports APK composition, largest files, Manifest metadata, permissions, exported components, basic DEX reference counts, and security-focused findings. Compare mode adds file-size, permission, component, and application-attribute changes. Use --open to open the generated report automatically; with --mode web --open, it opens the local Web report. APK is the supported input format in this release.

Common Commands

perfsight --help
perfsight help text
perfsight help web
perfsight help leak-capture
perfsight version
perfsight upgrade

Web mode also starts a local server at:

http://127.0.0.1:8765

Output Layout

PerfSight writes managed artifacts under output-dir with a package-scoped structure:

<output-dir>/
  sessions/<package>/<timestamp>/
    samples.csv
    session.json
    report.html
  captures/<package>/
  simpleperf/<package>/
  perfetto/<package>/
  logs/<package>/
  artifacts/
    inspect/<apk>/
    compare/<previous>__<current>/

--reset-output-dir clears the current package's existing sessions, captures, simpleperf, perfetto, and logs artifacts before a new run.

Text mode is quiet by default and prints startup, capture, dump, error, and exit events. Use --show-samples when you also want each periodic CPU/PSS sample line.

Web UI Features

• live App CPU chart
• live Total PSS and composition chart
• manual Dump Memory
• manual simpleperf Start Recording / Stop Recording
• manual Perfetto Start Trace / Stop Trace for app responsiveness timelines, including before the app process starts
• automatic leak-triggered dump capture
• reconnect-aware device state

On macOS, PerfSight bundles the simpleperf Gecko conversion runtime used to open CPU recordings in Firefox Profiler. Other hosts fall back to a local Android NDK simpleperf install when available. PerfSight uses the device-provided simpleperf record --app <package> -e task-clock:u -g path first, then falls back to PID-based strategies where needed. This avoids relying on the app's run-as access on user builds. Web mode performs a one-second CPU recording capability probe when the device connects and the target app is running. Probe files are removed from the device and are not exported as recording artifacts. Perfetto uses the device-provided binary and records Android scheduling, CPU frequency, UI, graphics, input, and frame timing. Its global Android trace categories retain cold-start system work such as activity management, Binder, Dalvik, resources, and memory. Active CPU and Perfetto recordings are stopped when PerfSight exits or loses its adb connection; a short device-side lease also stops and cleans abandoned recordings after host loss. Interrupted recordings are not recovered in a later run.

More Docs

• Documentation Index
• Leak Capture Design
• NPM Architecture
• Product Notes
• APK Artifact Analysis
• Development and Maintenance