IMPORTANT: Battery Historian 2.0 has been released. This article includes instructions that relate to the initial version of Battery Historian.
Battery Historian is an open source python script released by Google to profile battery related events on your Android Device. It was conceived as part of Google’s Project Volta that also saw the introduction of the new JobScheduler API to give developers some tools to develop apps that are good citizens when it comes to battery consumption.
It is useful for developers to investigate the impact their app is having on battery life by displaying a time line of events where the state of the most battery hungry sensors and features of Android are graphed.
Some typical use cases for Battery Historian would be:
- To show a wake lock is being acquired and released in the correct manner
- To verify the GPS is being turned off when your app no longer requires it
- To ensure your app isn’t constantly activating the mobile radio and preventing Android from entering a sleeping state
There are a few prerequisites that are required to use Battery Historian.
- An Android device running Android 4.4 or later
- Battery Historian script. Available from https://github.com/google/battery-historian
- ADB. You will need the Android Debug Bridge installed to issue commands to your Android device
- Python 2.x. Battery Historian is actually just a python script that processes the information in a battery stats dump from your device and builds a document to graphically represent the data. The python script that is Battery Historian is written for Python 2.x, and as such is not compatible with the latest Python 3.x. versions.
Tip: Using the python convert script 2to3.py does not correctly upgrade the python source. You need to either run the script with Python 2.x or convert and debug the script manually.
Generating a Battery Historian chart
It is just a quick couple of steps to setup and generate the battery stats chart using Battery Historian. You need to clear the existing bugreport data in the device, then perform any operations on your app, download the new data to your computer and run it through the python script to produce a lovely colorful representation of what has happened on your device.
Step 1: Prerequisites
Ensure you have checked all the items listed in the prerequisites section.
Step 2: Reset battery stats data on your device
All existing battery stats data needs to be removed from your device before we try to capture the data while your app is being used. To reset existing data make the following command line call:
adb shell dumpsys batterystats --reset
Step 3: Disconnect your device from your computer
Step 4: Test your app
Perform all the steps you want to do to test your app while the battery stats monitoring is taking place. If you are not tracking a specific bug then you can just try to exercise the areas of your app that may be triggering and stopping battery intensive operations.
If you are tracking a specific bug you will need to understanding what is happening under the hood of your app and which calls to which APIs are happening.
Step 5: Reconnect your device to your computer
Step 6: Generate bugreport
To generate the bugreport data and download it to your device you need to issue the following ADB command:
adb bugreport > batterystats.txt
This may take a couple of minutes to generate as the data file produced can be quite large.
Step 7: Generate the Battery Historian report
To generate the battery historian report from the bugreport output execute the historian.py script
python historian.py batterystats.txt > batteryreport.html
If you execute this script using python 3.x you will see an error such as SyntaxError: Missing parentheses in call to ‘print’.
Generating this report may produce an out of memory error due to the bugreport captured being too large, if this happens return to step 2 and start again with a smaller duration of testing your app.
Interpreting the Battery Historian chart
Open the html report generated to view your data. You will see a report similar to the image below:
Take a look at the period of time when your app was running, it will be shown in the row labelled top. This shows the topmost app running at any given time. Follow the list of rows down to see what is happening at the time your app was visible and running on your Android device. You should see the state of the screen, wake locks, GPS, WiFi, mobile data and other battery hogging events.
Remember that all running services could be affecting these readings as this data is not just in the domain of your app. Also remember that it may be that your battery drain issues may be caused during the period when your app is no longer topmost. You need to have a deep understanding of your services, what they are doing, when they are doing it, and how they are initiated to correctly interpret these charts.
Fixing common battery drain issues
Knowing what the common battery drain issues are and how to fix them will go a long to helping you understand why your app is producing the results in your Battery Historian chart. This is a vast topic in itself but a couple of the more common scenarios are:
- Explicit wake locks not being managed correctly. Don’t use explicit wake locks unless it is absolutely necessary. It is almost always not necessary to use them directly to keep the screen awake. As an alternative use LayoutParams.FLAG_KEEP_SCREEN_ON and remove this flag as soon as you no longer need the screen to remain on.
- Executing battery draining non-urgent tasks at inopportune times. Tasks that can be deferred until the device is on WiFi and/or charge can now be delayed using the simple and powerful JobScheduler API in Android 5.0+.
- Constant Polling of web services keeping the mobile radio alive. Take a look at a using SyncAdapter to reduce server polling or use inexact alarm schedules for tasks.
- Third party libraries such as Mobile Advertising or Analytics SDKs. It is easy to add libraries to your app but you must give consideration to the effect that library has on battery performance. Any library that transfers data to and from the internet is going to come with some costs. If it is a poor quality library it could cause major battery drain. Be careful what you include and profiling using Battery Historian after adding that any library is a smart move.
Battery Historian is not quite the powerful, easy to use battery performance tuning panacea that was trumpeted as part of Project Volta. It has very little documentation and isn’t great tracking down events over large time periods, for example on repeating alarm events, or events that only happen under very specific circumstances. However it is a useful tool that can help track issues such as ensuring wake locks, GPS and other energy sapping functionality are being handled correctly.
Battery Historian is another tool to add to your arsenal, even if just to give you some piece of mind that your app is being kind to your user’s battery. The best bet is as always understanding the fundamentals for battery performance turning and ensuring you are not violating best practice. Finally, don’t forget about one of the other pillars of Project Volta, the JobScheduler API.
Take a look at the Google I/O session below for more information about Battery Historian and Project Volta.