Capture and Analyze Android Battery Usage with Battery Historian

Step 3 – Install Battery Historian locally

Battery Historian is an open‑source web app written in Python. Running it locally guarantees that your usage data never leaves your machine.

Option 1 – Python virtual environment (cross‑platform)

1. Install Python 3.8+ and pip if they are not already present.
2. Open a terminal and create a virtual environment:

   python3 -m venv bh-env
   source bh-env/bin/activate   # macOS/Linux
   bh-env\Scripts\activate    # Windows

3. Clone the Battery Historian repository:

   git clone https://github.com/google/battery-historian.git
   cd battery-historian

4. Install dependencies:

   pip install -r requirements.txt

5. Start the server on port 9999:

   python3 historian.py --port 9999

6. Open a browser and navigate to http://localhost:9999. You should see the Historian upload page.

Option 2 – Docker (quick, isolated)

docker pull ghcr.io/google/battery-historian:latest
docker run -p 9999:9999 ghcr.io/google/battery-historian:latest

Docker handles all dependencies. Once the container is running, open http://localhost:9999 in a browser.

Step 4 – Load the captured data into Historian

Depending on the capture method you used, the upload steps differ slightly.

Uploading a bugreport

1. On the Historian web page, click Choose file and select bugreport.zip.
2. Press Upload. The tool extracts the batterystats protobuf and renders a timeline.

Uploading a raw batterystats dump

1. Rename the file to batterystats.txt if it isn’t already.
2. On the upload page, choose Upload file and select the text file.
3. Historian will parse the plain‑text format and generate the same visual output.

Step 5 – Understanding the Historian UI

The default view is a stacked timeline with several layers. Hover over any block to see a tooltip with exact timestamps and metrics.

• Wake locks – Indicates when an app or system service prevented the CPU from sleeping. Long wake‑locks are a common drain.
• CPU usage – Shows active CPU cores. Spikes often correlate with heavy processing.
• Network activity – Separate rows for Wi‑Fi, mobile data, and Bluetooth. Unexpected background traffic can be a red flag.
• Location requests – GPS usage is power‑hungry; frequent requests suggest a misbehaving app.
• Screen state – When the screen is on, the battery naturally drains faster. Use this as a baseline.

To isolate a suspect, click the Filter dropdown and select a specific app package name. The timeline will then highlight only that app’s contributions.

Practical example

Suppose you notice a 2‑hour battery drop after a morning commute. In Historian you see a continuous wake‑lock from com.example.news that starts at 08:15 and ends at 10:45. The tooltip reads “Wake lock held for 150 seconds”. This suggests the news app is keeping the device awake even when the screen is off, likely due to a background service.

Troubleshooting common issues

1. No data appears after upload

• Make sure you uploaded the correct file type (.zip for bugreport, .txt for raw dump).
• Check the console where Historian is running – any parsing errors will be printed.
• If the bugreport is corrupted (e.g., incomplete download), re‑run the capture.

2. "Permission denied" when resetting stats

• Reconnect the device and accept the RSA fingerprint prompt.
• On some OEMs (e.g., Xiaomi, Huawei), you must also enable USB debugging (Security settings) in the developer options.

3. Browser shows a blank page after upload

• Ensure JavaScript is enabled.
• If you’re using Docker, confirm the container’s port mapping is correct (host 9999 → container 9999).

4. The timeline is full of "unknown" entries

• This usually happens on Android 13+ where the batterystats protobuf version changed. Update Battery Historian to the latest commit (pull the repo again) and restart the server.

Advanced tips and edge cases

• Split‑tunneling analysis: If you use a VPN, enable the Show network activity per UID filter to see whether the VPN app itself is the drain.
• Battery health check: Historian also displays the Battery level line. Sudden drops may indicate a hardware issue rather than software.
• Long‑term monitoring: Automate periodic dumps with a simple shell script and schedule them via adb shell crontab (requires a rooted device). For non‑root, you can use Tasker to trigger adb shell dumpsys batterystats over Wi‑Fi.
• Exporting the report: Click the Export as CSV button to download raw event data. This is handy for sharing with developers when filing bug reports.

Safety and privacy considerations

Wrapping up

By resetting the stats, capturing real‑world usage, and feeding the data into Battery Historian, you gain a visual, data‑driven view of what’s draining your Android battery. The process requires only ADB and a local Python (or Docker) installation, so it works on any device without rooting.

Once you identify the offending wake‑lock or network spike, you can take concrete action: disable background sync, force‑stop the app, adjust its battery‑optimisation settings, or report a bug to the developer. Re‑run the capture after making changes to verify the improvement – a reduced wake‑lock duration or lower network usage is a good sign.

Regularly repeating this workflow (e.g., once a month) helps you keep your device’s power profile healthy, especially after installing new apps or system updates.