ProcessLens
1.2 · GitHub
More about this app
Process observatory using Shizuku for ADB-level CPU, memory, thread, wake lock and per-app battery readings.
ProcessLens
A process observatory for Android that refuses to make things up.
Watch what your phone is actually doing — processes, threads, CPU, memory, wake locks, network, battery — and record an investigation you can scrub back through afterwards.
Android 8.0 or newer · 12 MB · no account, no network permission · all releases
The idea
Every system monitor on Android runs into the same wall. Since Android 7 an app can no
longer read /proc for processes it does not own, and each release since has closed
another door. Most apps respond by quietly showing you a plausible number anyway.
ProcessLens does the opposite. Every reading it displays is wrapped in a type that can only be one of three things:
sealed interface Observed<out T> {
data class Value<out T>(val value: T, val source: DataSource, val precision: Precision)
data class Restricted(val reason: RestrictionReason, val unlockedBy: AccessLevel?, val detail: String)
data class Failed(val detail: String, val cause: String?)
}
There is no fourth case, and no default. If the platform will not tell ProcessLens something, the screen says so — which permission or access level would reveal it, and why it is hidden. A dash is never a zero, and the app says as much where you might mistake one for the other.
The same rule governs the analysis. A spike that lines up with an app waking the device is reported as a potential correlation, never a cause, because timestamps that happen to agree are not proof. Battery figures the platform does not expose are absent rather than estimated.
What it does
Watch — a live dashboard of CPU, memory, storage and battery, refreshing every 1, 2, 5 or 10 seconds, or only when you ask. Per-core utilisation and clock speeds where the kernel exposes them, load average, thermal zones.
Inspect — the full process list with sorting and filtering, then per-process detail: state, UID, start time, CPU time, threads, and the parent/child tree. Installed apps with their components, requested permissions and grant state, and which of their services are running right now.
Investigate — start a recording, use your phone normally, then stop. ProcessLens samples throughout and gives you a timeline of colour-dotted events: resource spikes against thresholds you set, wake locks acquired, processes appearing and vanishing. Scrub back through it, compare two apps side by side, and export the whole thing as JSON, CSV or plain text.
Understand its own limits — a Capabilities screen listing all 37 metrics ProcessLens knows how to read, grouped into nine areas and each marked available or not on your device, computed at runtime from what actually works rather than assumed from a version number.
Access levels
Most of the app works with no special access at all. Two optional paths widen what the kernel will admit to:
| Reads | |
|---|---|
| Normal | Own process in full, device-wide CPU and memory, battery, network state, installed packages, running services, usage stats with permission |
| Shizuku | Adds ADB-level shell observation: other processes' CPU and memory, threads, the real process tree, wake locks, per-app battery |
| Root | Adds unrestricted /proc and full dumpsys |
Shizuku is not root and ProcessLens does not pretend otherwise — it distinguishes all six states it can be in (not installed; installed but not running; running with permission not yet requested; running with permission denied; running with permission granted; running an unsupported version) and tells you which capabilities each would unlock.
There is no "kill everything" button, no arbitrary shell, and no one-tap destructive command. Process Details will not offer you a bare Kill button, because a tool for understanding a system should not make it trivially easy to break one.
Privacy
Not a policy — a property of the build.
android.permission.INTERNETis not in the manifest. The app cannot open a socket even if it wanted to. Verified absent from the shipped APK.- No account, no sign-in, no cloud, no analytics, no telemetry, no crash reporting service.
- Recordings, favourites and settings live in a local Room database and never leave the device unless you export a file and share it yourself.
- If the app ever crashes it writes the stack trace to your
Downloadsfolder — a plain text file, yours to read, delete or send on.
Build it yourself
git clone https://github.com/Dreamucxe/ProcessLens.git
cd ProcessLens
chmod +x gradlew
./gradlew assembleRelease
Requires JDK 17 and an Android SDK with platform 34 and build-tools 34.0.0.
gradle.properties is committed exactly as it was when the released APK was built —
on an aarch64 Android device under proot, not a workstation. That is why it pins
org.gradle.java.home, overrides aapt2 with a native ARM binary, disables the Gradle
daemon and runs the Kotlin compiler in-process. On a normal machine, delete those four
lines.
Release builds are signed only if you drop a keystore.properties next to settings.gradle.kts:
storeFile=release.keystore
storePassword=…
keyAlias=…
keyPassword=…
Without it you get an unsigned APK; the signing key for the published release is not in this repository.
Tests
./gradlew testDebugUnitTest # 396 JVM tests
./gradlew connectedDebugAndroidTest # 90 instrumented tests, needs a device
The unit tests cover the /proc parser against fixture filesystems, CPU rate sampling,
spike detection, export rendering, investigation recording and the search, sort and filter
logic. The instrumented tests drive the real UI and deliberately use no testTag
anywhere in production code — every node is found by its visible text or its content
description, so a test that cannot find something is also telling you a screen reader
could not.
Architecture
core/
common Observed<T>, AccessLevel, formatters, fuzzy matching
designsystem theme, glass cards, charts, bottom sheets
system SystemObserver + Standard / Shizuku / Root implementations
permissions runtime and special-access checks
data/
database Room entities, DAOs, migrations, exported schemas
repository repository implementations
domain/
model Capability, ProcessInfo, Investigation, UserSettings
usecase spike detection, recording, summarising, export
feature/ 19 screens, one package each, MVVM with Hilt
Kotlin · Jetpack Compose · Material 3 · MVVM · Hilt · Room · Coroutines. The UI never
calls a shell command or a privileged API directly; everything goes through
SystemObserver, which routes to the highest access level currently available and falls
back cleanly when it is withdrawn.
Licence
MIT — see LICENSE.
How Shizuku is used
Can list processes, threads, wake locks, services, per-app battery and exact memory via Shizuku with `ps`, `dumpsys` and `/proc` reads.
This is an AI-assisted analysis of Shizuku-related usages in the app's public source code. It is best effort, so it may not catch every single usage.
How this app uses Shizuku
ProcessLens uses Shizuku as an ADB level shell to run read-only system diagnostics that the normal sandbox hides.
- List all processes: shows the complete system process table with PIDs, users, CPU time and memory by running
ps -Athrough Shizuku, enriched with platform memory figures fromdumpsys meminfo. - Show thread details: lists threads of a selected process and reads per-thread CPU and state via the thread entries under
/procthrough Shizuku when direct access is denied. - View wake locks: reads currently held wake locks from
dumpsys powerthrough Shizuku and labels them with the owning app where possible. - List running services: reads running services across all packages from
dumpsys activity servicesthrough Shizuku, optionally filtered to one app. - Attribute battery use: shows per-app battery attribution from the platform battery statistics via
dumpsys batterystatsthrough Shizuku. - Show exact memory: shows per-process PSS memory as computed by the platform from
dumpsys meminfothrough Shizuku.
Android APIs or commands used
ps -A -o PID,PPID,USER,RSS,VSZ,STAT,TIME,NAMEdumpsys meminfodumpsys powerdumpsys batterystats --chargeddumpsys activity servicesls /proc/[pid]/taskcat /proc/[pid]/task/[tid]/stat
Notable details
Without Shizuku the app still works with normal APIs, but shell only sections show as unavailable and process, thread, wake lock, service, battery and PSS lists are limited or fall back to the standard observer.
Changelog
What's new for version 1.2
Fixes the Overview loading hang (#1)
The dashboard no longer sits on "Reading system state" at launch. Overview resolves on the first frame, with or without root.
Root cause: the Overview state was a combine() of five flows, and one of them never emitted on a cold start — so the screen never left its loading state. Navigating to Settings → Access happened to write that missing value, which is why tapping "Probe root" appeared to fix it; the root grant was incidental. The SELinux avc: denied messages in the report were a real but separate defect, fixed here as well.
Also in this build
- A denied
/procor/sysread now resolves once per session to "N/A (restricted by Android)" instead of being re-attempted on every 2 s tick — no more repeating denial spam in logcat. - Shell probes (
su, Shizuku) have a real deadline and drain stdout and stderr concurrently. Ansucall parked on an unanswered superuser prompt can no longer block collection. - A granted root session is no longer wiped when access is re-evaluated.
- Per-metric restriction labels that say what would unlock them, a non-blocking no-root banner, and a manual re-probe action.
435 unit tests pass. Full write-up in #4 and docs/ISSUE1_ROOT_CAUSE.md.
Build note: signed release build, not processed by R8 — produced on an ARM device that cannot run the shrinker within its memory budget. Functionally identical to a shrunk build; the APK is just larger and unobfuscated.
Version: reports as 1.2 (versionCode 2). Every earlier release shipped an APK that still identified itself as 1.0 (versionCode 1), so this is the first build a device sees as an actual upgrade. It is signed with the same key as before, so it installs over an existing copy without uninstalling.
Permissions
10 permissions requested