Bugreport

Capturing System State

A bugreport is the ultimate diagnostic artifact in Android. It is a comprehensive snapshot of the device's state at a specific moment in time. When a user or tester encounters a complex issue, capturing a bugreport is the standard procedure.

You generate a bugreport using adb:

adb bugreport

This command triggers the bugreportd daemon, which orchestrates the collection of data and packages it into a .zip file on your host machine.

Bugreport Contents

The resulting zip file (bugreport-<device>-<date>.zip) is densely packed with diagnostic information. The most critical file is the main text file, usually named bugreport-<device>-<date>.txt.

Key components included in a bugreport:

• dumpsys: The output of dumpsys for every running system service (e.g., dumpsys window, dumpsys activity, dumpsys batterystats).
• logcat: The complete historical buffers (main, system, events, crash).
• dmesg: The kernel ring buffer.
• Traces: Thread dumps (ANR traces) from /data/anr/.
• Tombstones: Native crash dumps from /data/tombstones/.
• Properties: The output of getprop.

The bugreportz Format

Modern Android versions use the bugreportz protocol. Instead of streaming raw text over ADB (which was slow and prone to interruption), bugreportz zips the data locally on the device and then transfers the compressed archive.

This format allows the inclusion of multiple files (like SQLite database dumps from batterystats or raw tombstone files) rather than relying on a single, massive text file.

Analyzing Bugreports

Because a bugreport text file can easily exceed 500,000 lines, manual parsing is difficult.

Battery Historian

For power and battery issues, Google provides Battery Historian. You can upload the bugreport zip to this tool to get a visual timeline of wakelocks, radio state, and CPU usage.

Android Studio integration

Android Studio has built-in tools for analyzing bugreports.

1. Open Android Studio.
2. Navigate to Profiler or use the App Inspection tools.
3. You can import a bugreport to view memory allocation, thread states, and logcat data within the IDE's UI, making it significantly easier to filter and search through the massive amount of data.