Capture and Analyze Android Battery Usage with Battery Historian

When your phone seems to run out of juice faster than it should, the first question is what is actually consuming the power. Android records detailed battery statistics internally, but the raw data is not human‑readable. Battery Historian is an open‑source web tool that turns those logs into clear graphs, letting you see which apps, wake‑locks, or hardware components are responsible.

Before you start

• Charge your device to at least 50 %. Battery‑stat collection can be inaccurate on a near‑empty battery.
• Enable Developer options and USB debugging (Settings > About phone > tap Build number 7 times, then Settings > System > Advanced > Developer options).
• Install adb on your PC. You can download the platform‑tools zip and extract it to a folder that is in your PATH or reference it directly.
• Make sure your PC can communicate with the phone: connect via USB, accept the RSA prompt on the device, then run adb devices to see the device listed.
• Have a recent version of Python 3 installed (required to run Battery Historian). If you prefer not to install Python, the pre‑built JAR version can be used – the steps are included.

What Battery Historian does

Battery Historian parses the batterystats binary that Android writes every time a bug report is generated. It then displays:

• Screen‑on/off timelines.
• CPU wake‑locks held by each app.
• Network activity spikes.
• Sensor usage (GPS, accelerometer, etc.).
• Battery level changes over time.

By correlating these events you can answer questions like:

• Which app kept the device awake while the screen was off?
• Did a misbehaving service cause a sudden battery drop?
• Is the Wi‑Fi radio staying on longer than necessary?

Step 1 – Install ADB and verify the connection

Step 2 – Capture a battery‑stats dump

Battery Historian works with two kinds of logs: a full bug report (which includes the batterystats file) or a direct dumpsys batterystats output. The bug‑report method gives the most detail, but requires a bit more storage.

Step 3 – Install Battery Historian

Battery Historian is distributed as a .jar file that runs on any platform with Java, and a small Python helper script to launch a local web server.

Step 4 – Load the bug report into Battery Historian

Step 5 – Interpreting the graphs

Battery Historian can be intimidating at first, so we’ll walk through the most common patterns.

5.1 Screen‑on vs. Screen‑off

The thick green bar at the top represents the screen state. If you see long green periods while you thought the phone was idle, an app may be preventing the screen from turning off. Check the Wake lock rows for the same timestamps.

5.2 Wake‑locks

Each app that acquires a partial or full wake‑lock gets its own row. A wake‑lock that stays active for minutes while the screen is off is a classic battery‑drain culprit. Note the app name and the duration, then consider:

• Disabling background activity for that app (Settings > Apps > [App] > Battery > Background restriction).
• Checking for a newer version that may have fixed a bug.

5.3 Network activity

Spikes in the “Network” row often coincide with sync services, cloud backups, or misbehaving apps constantly polling servers. If the spikes line up with a particular app’s wake‑lock, that app is likely the offender.

5.4 GPS / Sensor usage

Location‑related rows appear as purple bars. Continuous GPS use is a major drain; look for apps that hold the location sensor for long periods.

5.5 Battery level drop

The bottom‑most line shows the battery percentage over time. Sharp drops without corresponding screen activity usually indicate a hardware issue (e.g., a failing battery) or a kernel‑level bug. If the drop aligns with a software event, you have a clear target.

Common troubleshooting scenarios

Scenario 1 – No data appears after upload

• Make sure you uploaded the bugreport.zip that contains a batterystats file. Some OEM bug reports omit this file; in that case, use the dumpsys batterystats method instead.
• Check the browser console for errors (press F12). If you see Failed to load resource, the JAR may not have permission to read the zip – try moving the file to the same directory as the JAR.

Scenario 2 – Battery Historian crashes with a Java exception

• Ensure you are running Java 8 or newer. Older JRE versions lack required APIs.
• On macOS, you may need to grant the terminal full disk access (System Settings > Privacy & Security > Full Disk Access).

Scenario 3 – The timeline shows only a few seconds of data

• Bug reports capture data only for the period while the device is generating the report. For longer‑term analysis, repeat the adb bugreport command after a few hours of normal use, then merge the two reports using the --merge flag of Battery Historian (available in newer releases).

Advanced tips and edge cases

• Android 12+ restrictions: Starting with Android 12, the system limits how often dumpsys batterystats can be invoked without root. If you hit a permission error, use the bug‑report method instead.
• Automating data collection: You can schedule periodic dumps with a simple shell script on your PC:

  while true; do
    timestamp=$(date +%Y%m%d_%H%M%S)
    adb shell dumpsys batterystats > "batterystats_$timestamp.txt"
    sleep 3600  # one hour interval
  done

  This creates hourly snapshots you can later load individually.
• Using the built‑in Power Profile: Some devices expose a settings put global power_profile command that can temporarily switch to a low‑power mode for testing. Combine this with Battery Historian to see the quantitative effect.
• Exporting the analysis: Battery Historian lets you download the rendered SVG chart via the Export PNG button. Save the image for a quick visual reference when reporting a bug to the app developer.

Safety warnings

• Do not enable USB debugging on a device that you leave unattended in a public place – anyone with physical access could issue ADB commands.
• When capturing a bug report, the device temporarily stores a large amount of log data in memory. Avoid doing this while the battery is critically low.
• Never share the full bug‑report file publicly; it can contain personal data, Wi‑Fi passwords, or other sensitive information. If you need to post a snippet, extract only the batterystats section.

Wrapping up

By following the steps above you now have a repeatable workflow:

1. Enable USB debugging.
2. Capture a bug report (or dumpsys batterystats) after a period of typical usage.
3. Run Battery Historian locally and load the log.
4. Identify wake‑locks, network spikes, or sensor usage that do not match your expectations.
5. Apply targeted fixes – restrict background activity, update or uninstall offending apps, or adjust system settings.

Because the process is entirely on‑device and uses only free, open‑source tools, you can repeat it whenever a new drain appears, without ever rooting your phone. Over time you’ll develop an intuition for the “normal” battery pattern of your device, making future problems easier to spot.

Happy debugging, and may your battery last longer!