+The Battery Historian tool provides insight into a device’s battery consumption +over time. At a system-wide level, the tool visualizes power-related events from +the system logs in an HTML representation. At an app-specific level, the tool +provides a variety of data that can help you identify battery-draining app +behavior. +
+ ++This document describes some of the ways you can use Battery Historian +to learn about battery-consumption patterns. The document begins by explaining +how to read the system-wide data that Battery Historian reports. Then, +it presents ways in which you can use Battery Historian to diagnose +and troubleshoot your own app's behavior related to battery consumption. +Last, it offers several tips on scenarios in which Battery Historian may be +particularly useful. +
+ ++The Battery Historian tool provides a system-wide visualization of various +app and system behaviors, along with their correlation against battery +consumption over time. This view, shown in Figure 1, can help you +diagnose and identify power use issues with your app. +
+ +
+ +Figure 1. +Battery Historian’s display of system-wide events affecting power +consumption. +
+ ++Of particular interest in this figure is the black, horizontal, downward trend +line representing Battery Level, measured on the y-axis. For example, at the +very beginning of the Battery Level line, at approximately 6:50 AM, the +visualization shows a relatively steep drop in battery level. +
+ ++Figure 2 provides a close-up of that part of the display. +
+ +
+ +Figure 2. +A close-up of the Battery Historian timeline from roughly 6:50 AM to 7:20 AM. +
+ ++At the very beginning of the Battery Level line, as battery decline steeply, +the display shows three things happening: The CPU is running, an app has +acquired a wakelock, and the screen is on. In this way, Battery Historian helps +you understand what events are happening when battery consumption is high. You +can then target these behaviors in your app and investigate whether there are +related optimizations you can make. +
+ ++The system-wide visualization can provide other clues, as well. For instance, if +it shows that the mobile radio is frequently being turned off and on, there may +be an opportunity to optimize this behavior through intelligent scheduling APIs such as JobScheduler or +Firebase Job Dispatcher. +
+ ++The next section explains how to investigate behavior and events specific to +your own app. +
+ ++
+In addition to the macro-level data provided by the system-wide view, Battery +Historian also provides tables and some visualization of data specific to each +app running on your device. The tabular data includes: +
+ ++The tables provide two dimensions of data about your app. First, you can look +up where your app’s power usage ranks compared to other apps. To do so, click +Device Power Estimates table under Tables. This example +examines a fictional app called Pug Power. +
+ +
+ +Figure 3. Investigating which apps consume the most power. +
+ ++The table in Figure 3 reveals that Pug Power is the ninth biggest consumer of +battery power on this device, and the third biggest app that is not part of the +OS. This data suggests that this app bears deeper investigation. +
+ ++To look up the data for a specific app, enter its package name into the lower +of the two dropdown menus under App Selection, located under the left +side of the visualization. +
+ +
+ +Figure 4. Entering a specific app whose data to view. +
+ ++When you select a specific app, the following data visualization categories +change to display app-specific data instead of system-wide data: +
+ ++You can also obtain one more piece of app-specific visualization data, +Userspace Wakelock. To include this information in the bug report, +enter the following command in your terminal window: +
+ ++$ adb shell dumpsys batterystats --enable full-wake-history ++ +
+Note: From Android 6.0 (API level 23), the platform includes +Doze functionality, which imposes certain optimizations on apps. For example, +Doze batches jobs to take place during brief maintenance windows, regardless of +how JobScheduler has scheduled them. +
+ ++Figures 5 and 6 show data for Pug Power: Figure 5 +shows the visualization of +the app-specific data, and Figure 6 shows the corresponding tabular data. +
+ +
+ +Figure 5. Visualization of data for fictional app Pug Power. +
+ +
+ +Figure 6. Tabular data for the fictional Pug Power app. +
+ ++A look at the visualization does not show anything immediately obvious. +The JobScheduler line shows that the app has no jobs scheduled. The SyncManager +line shows that the app has not performed any syncs. +
+ ++However, examination of the Wakelocks segment of the tabular data +reveals that Pug Power acquires wakelocks totaling over an hour. This unusual +and costly behavior can account for the app’s high level of power consumption. +This piece of information helps the developer target an area where optimization +is likely to greatly help. In this case, why does the app acquire so much +wakelock time, and how can the developer ameliorate this behavior? +
+ ++There are many other cases in which Battery Historian can help you diagnose +opportunities for improving battery behavior. For example, Battery Historian +can tell you if your app is: +
+ +