Battery life is important for a mobile device. So, when a user downloads and uses your app they expect your app to value battery life. That means if your app is a battery hog, then it won’t be long before your app gets uninstalled. It doesn’t matter how amazing your app is, but if your app is the reason why someone needs to find a phone charger a few hours into their day then they’ll uninstall your app.
Luckily, there are tools out there to help you profile your app’s battery consumption so you can find out if your app is a battery hog. To profile your app’s battery usage, you’ll need two tools, Batterystats and Battery Historian. For this post, I’ll be showing you the basic usage and workflow of the Batterystats tool and the Battery Historian script.
Note: The steps in this post are done on a mac. It is likely the steps will be different for Linux and or Windows.
What Is Batterystats and Battery Historian
You might be wondering what exactly is Batterystats and Battery Historian. To put it simply, Batterystats is a tool included in the Android framework that collects battery data on your device. You can use adb (Android Debug Bridge) to dump the collected battery data to your development machine and create a report that you can analyze with Batter Historian. Battery Historian converts the report from Batterystats into an HTML visualization that you can view on a browser.
Something important to note is that Batterystats is not something magical that will tell you exactly where in your app are battery drains occurring the most. You will still have to put in the work to pinpoint battery drain issues in your app. With that said, what Batterystats is good for are the following:
- To show you where and how processes are drawing current from the battery
- Identifying tasks in your app that could be deferred or removed to improve battery life
Installing Battery Historian
To install Battery Historian you’ll need to install Docker. If you already have Docker installed then you can just run Battery Historian with the following command line:
docker --run -p port_number:9999 gcr.io/android-battery-historian:2.1 --port 9999
Note: You can choose a random port number to use as long as it is not a special port. For example, don’t use port 443 because it is for HTTPS.
If you don’t have Docker installed then you would want to install Docker Community Edition by following the instruction on the Docker website. Once installing is complete, ensure that Docker is running.
With Docker installed and running, you can run Battery Historian with the following steps.
- In a terminal enter the following command line to run Battery Historian
docker --run -p port_number:9999 gcr.io/android-battery-historian:2.1 --port 9999
You can choose a random port number to use as long as it is not a special port. For example, don’t use port 443 because it is for HTTPS.
- You can navigate to Battery Historian through your web browser of choice. The URL is http://localhost/port_number. The port_number is the port number you chose when entering the command line to start Battery Historian with Docker.
- You will see the Battery Historian start page where you can upload and view battery statistics.
Gathering Data with Batterystats
To collect data with Batterystats, you need to do the following:
- Enable developer mode and USB debugging on your mobile device
- Connect your mobile device to your development machine
- From a terminal, shutdown the current running adb server
adb kill-server
- Restart adb and check for connected devices
adb devices
- Reset battery data gathered
adb shell dumpsys batterystats --reset
Note: The device is always collecting batterystats and other info in the background. That is why you want to reset Batterystats, which will erase the old battery data.
- Disconnect your mobile device and make sure the only power source for your device is the battery
- Launch your app and perform actions you would like to gather battery usage for. E.g. Bring up GPS related activities or activities that connect to an external database.
- Reconnect your device
- Make sure your mobile device is recognized by adb
adb devices
- Dump all the battery data gathered since reset. This can take a while depending on how long you were running your app.
adb shell dumpsys batterystats > <mobile_phone_internal_storage_path>/batterystats.txt
- Create a report from raw data
For Android 7.0 and above use the following command lineadb bugreport > <mobile_phone_internal_storage_path>/bugreport.zip
For Android 6.0 and under use the following command line
adb bugreport > <mobile_phone_internal_storage_path>/bugreport.txt
- Get the report from your mobile device
adb pull <mobile_phone_internal_storage_path>/bugreport.zip
- The report file will be in the directory where you ran the adb pull command
Viewing the Data with Battery Historian
In the web browser, you can upload the report into Battery Historian to get a nice visualization of the battery usage. There is a lot of information and the area of interest will really depend on what you are looking to check about your app. There is a filter that you can apply to show only app-specific information.
Troubleshooting
I can’t use Docker to run Battery Historian.
Try using `run` instead of `–run`. If you don’t have Battery Historian locally available, Docker will go off and download it. For example, this would be the command line you might use instead:
docker run -p port_number:9999 gcr.io/android-battery-historian:2.1 --port 9999
Note: You can choose a random port number to use as long as it is not a special port. For example, don’t use port 443 because it is for HTTPS.
ADB commands don’t work
Make sure adb can see your device. For ease of use, make sure that only one device is connected to your machine and there are no Android emulators running. When there are multiple devices and or emulators, adb requires you to specify which device gets the command.
ADB shell commands don’t work
If the adb shell command doesn’t work you will need to go directly into the shell of the mobile device. To do that make sure adb detects your device then go into the device’s shell.
adb shell
Now you can run the adb shell commands that you need, but without including “adb shell”. For example, the original command line is
adb shell batterystats --reset
will now be
batterystats --reset
because you are already in the device’s shell.
Note: This is a good time to create a directory for placing the batterystats files if you would like to do so. Navigate to where you want to create a new directory in your device then create the directory with the mkdir command.
ADB pull can’t find the report
Make sure you know where the report file is generated in your mobile device. Make sure there are no typos in your path.
An alternative is to create the report at a location that is accessible by simply connecting your mobile device to a computer. That way, you can just copy the file over through a file explorer.
I hope this post was helpful to you. If you found this post helpful, share it with others so they can benefit too.
To get in touch, you can follow me on Twitter, leave a comment, or send me an email at steven@brightdevelopers.com.