ShizuStore

ProcessLens

Dreamucxe

1.2 · GitHub

Download APK
Task manager Android 8.0+ 1 month ago MIT
464 ShizuStore
841 GitHub
24 Stars
12 MB Size

More about this app

Process observatory using Shizuku for ADB-level CPU, memory, thread, wake lock and per-app battery readings.

ProcessLens

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.

Download ProcessLens.apk

Android 8.0 or newer · 12 MB · no account, no network permission · all releases

Android 8.0+ Kotlin Compose Tests No network


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.INTERNET is 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 Downloads folder — 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.

Close

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 -A through Shizuku, enriched with platform memory figures from dumpsys meminfo.
  • Show thread details: lists threads of a selected process and reads per-thread CPU and state via the thread entries under /proc through Shizuku when direct access is denied.
  • View wake locks: reads currently held wake locks from dumpsys power through Shizuku and labels them with the owning app where possible.
  • List running services: reads running services across all packages from dumpsys activity services through Shizuku, optionally filtered to one app.
  • Attribute battery use: shows per-app battery attribution from the platform battery statistics via dumpsys batterystats through Shizuku.
  • Show exact memory: shows per-process PSS memory as computed by the platform from dumpsys meminfo through Shizuku.

Android APIs or commands used

  • ps -A -o PID,PPID,USER,RSS,VSZ,STAT,TIME,NAME
  • dumpsys meminfo
  • dumpsys power
  • dumpsys batterystats --charged
  • dumpsys activity services
  • ls /proc/[pid]/task
  • cat /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.

Close

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 /proc or /sys read 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. An su call 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.

Close

Permissions

10 permissions requested

  • android.permission.PACKAGE_USAGE_STATS
  • android.permission.ACCESS_NETWORK_STATE
  • android.permission.READ_PHONE_STATE
  • android.permission.QUERY_ALL_PACKAGES
  • android.permission.FOREGROUND_SERVICE
  • android.permission.FOREGROUND_SERVICE_DATA_SYNC
  • android.permission.POST_NOTIFICATIONS
  • android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS
  • moe.shizuku.manager.permission.API_V23
  • com.processlens.DYNAMIC_RECEIVER_NOT_EXPORTED_PERMISSION
Close