A dumpsys tour

adb shell dumpsys is a single command that can tell you the state of nearly every service on the device. It is not a debugger, it does not attach to anything, and it does not require a debuggable build. It works because of one convention: every system service implements dump().¹

TL;DR#

• dumpsys <name> looks up the Binder service, calls its dump() method, and prints what it writes.
• dumpsys -l lists every service that can be dumped. That list is the same service list you saw in the previous page, filtered to services that implement the interface.
• The output format is whatever the service decided — there is no schema. Reading it is a skill, not a syntax.
• The most valuable flags are the ones that select a subsection: dumpsys activity activities, dumpsys window windows, dumpsys package <pkg>.
• cmd <service> <command> is the sibling command for changing state; dumpsys only reports.

Mental model#

Think of a building where every office is required, by law, to answer one question: "describe yourself, in writing, right now."

dumpsys is the inspector who walks in and asks it. Some offices hand over a two-page summary; some hand over four hundred pages of internal ledgers. The inspector does not reformat anything. Your job is to know which office to visit and which page to read.

Where the analogy breaks#

An inspector can ask follow-up questions. dumpsys cannot: it calls dump() once with whatever arguments you supplied and prints the result. If the service did not implement a subsection for your question, the answer is not there, and no amount of retrying will produce it. The remedy is to read the source of that service's dump method.

The big picture#

Deep dive#

What dumpsys actually does#

The shell command is a thin Java program, Dumpsys.java, that runs inside app_process. It:

1. Takes the service name argument.
2. Looks the name up with ServiceManager.getService(name).
3. If the service exists, calls service.dump(fd, args) over Binder, passing a file descriptor for stdout.²

That last part is the interesting one. dump() takes a FileDescriptor, not a return value. The service writes directly to the pipe. This is why a dump can be hundreds of megabytes without ever materialising a string in the service's heap, and why dumpsys > file is the normal way to capture one.

Listing and filtering#

$ 
adb shell dumpsys -l
adb shell service list | wc -l

Currently running services:
activity
activity_task
alarm
android.security.keystore2
appops
…

dumpsys -l lists services that can be dumped. service list lists every registered Binder service, which is a superset: some services are registered but have no useful dump, and some are registered by native processes rather than the framework.

The full output of dumpsys with no arguments is enormous, because it walks the entire list. Do not run it on a production device unless you need a bugreport-grade snapshot; run it on a test device, or redirect it to a file.

The tour: six dumps worth knowing#

dumpsys activity activities — the task and activity stack. This is where you find out why an app is not resuming, what task it ended up in, and which activity is on top of which. Look for state=RESUMED, visible=true, and the task's A= (UID) field.

dumpsys window windows — the window hierarchy with z-order. Look for mBaseLayer and the window's owner. This answers "why is this dialog behind the keyboard" and "which window has focus".

dumpsys package <pkg> — everything PackageManager knows: version, userId, targetSdk, declared permissions, granted permissions, components, and the app's install path. It is the fastest way to confirm what is actually installed.

dumpsys meminfo <pkg> — the memory breakdown: PSS by category, the Java heap, the native heap, and the process's oom_adj. This is the canonical answer to "how much memory is this app using".

dumpsys gfxinfo <pkg> — frame timing. With framestats it gives per-frame timings for a recent window of frames, which is how you tell a jank problem from a slow-start problem without a profiler.

dumpsys batterystats — wakelocks, alarms, job scheduling and per-UID power attribution. It is the source behind the battery screen and the reason dumpsys batterystats --reset exists.

The catalogue, filtered to dumpable services#

Reading a dump without drowning#

Three habits make the difference between a dump and an answer.

Narrow with a subcommand. dumpsys activity prints activities, processes, services, providers and broadcasts. dumpsys activity activities prints one of those. The subcommand is matched by the service's own dump implementation, so the list of valid subcommands is in the source, not in the help text.

Grep for structure, not for values. Grepping for your package name is fine. Grepping for state= inside dumpsys activity activities gives you one line per activity and a much smaller output to read.

Capture, then read. A dump is a snapshot; reading it while it scrolls is guesswork. Redirect to a file, then use an editor.

$ 
adb shell dumpsys activity activities > /tmp/activities.txt
grep -A3 "com.example.app" /tmp/activities.txt

Task{7f3a1c2 #1234 type=standard A=10123:com.example.app}
ActivityRecord{8a2b3c4 u0 com.example.app/.MainActivity t1234}
  state=RESUMED visible=true

dumpsys versus cmd#

They are siblings and are often confused.

• dumpsys <service> reads. It calls dump().
• cmd <service> <command> writes. It calls shellCommand(), which the service implements separately.

So dumpsys package com.example.app tells you what permissions the app holds, and cmd package grant com.example.app android.permission.CAMERA changes them. dumpsys has no way to change anything; cmd has no standard output format.

The bugreport#

adb bugreport is what happens when you run essentially every dump, plus logs, plus system properties, plus a copy of the package database. It is dumpsys at maximum breadth, and it is the format that field support and Google's own tooling consume.

That is why there are two different questions worth separating: "I want to understand this one subsystem" (use a targeted dumpsys) and "I need a complete record for someone else" (use bugreport). Reaching for the second when you need the first is a common way to spend twenty minutes waiting for a file you will not read.

How it evolved#

The command has been stable for a very long time, and the changes have been in what the services choose to print. dumpsys gfxinfo gained the framestats mode, which turned it from a summary into a per-frame trace. dumpsys activity grew the activities / processes split when ActivityTaskManager was carved out. The interface itself — dump(fd, args) — has not changed.

Under the hood#

• ‹›Dumpsys.java↗the shell command itself: it resolves a name and calls dump(fd, args)
• ‹›Binder.java↗the base dump implementation every service overrides
• ‹›ActivityManagerService.java↗a dump method large enough to have its own subcommand dispatch
• ‹›WindowManagerService.java↗the window dump: hierarchy, layers, focus and insets

Curiosity corner#

• dumpsys can hang. If a service holds its lock and the dump path needs the same lock, your command blocks. A dump that never returns is evidence, not an accident.
• The output is not a stable API. Services add, remove and reorder fields between releases. Any tooling that parses dumpsys output is parsing a debug format, not a contract.
• dumpsys SurfaceFlinger is a different program's dump. SurfaceFlinger is native, and its dump is implemented in C++; the command is the same convention across the whole system.

Try it#

$ 
adb shell dumpsys -l | head -40
adb shell dumpsys activity activities | head -40
adb shell dumpsys window windows | grep -E "Window #|mBaseLayer" | head -20
adb shell dumpsys meminfo | head -30
adb shell dumpsys jobscheduler | grep -E "Registered|Pending" | head -20

Run these in order on a device you can afford to poke at. The first tells you what exists, the next three tell you what is running and where it is drawn, and the last tells you what the system intends to do next.

Check yourself#

Sources#