1page.title=Batterystats & Battery Historian Walkthrough
2meta.tags="android, performance, profiling, tools, battery, batterystats, historian, batterydrain
3page.tags="android", "performance", "profiling", "tools", "battery", "batterystats", "historian", "batterydrain"
4page.metaDescription=Collect battery usage data from your device and display it graphically in your browser.
5page.image=tools/performance/thumbnails/tools_battery_historian.png
6page.article=true
7
8
9@jd:body
10
11<div id="tb" style="margin-left: 7px; margin-bottom: 5px;">
12
13<h2>You should also read</h2>
14<ul>
15  <li><a href="{@docRoot}tools/performance/batterystats-battery-historian/charts.html">
16    Battery Historian Charts</a></li>
17  <li><a href="{@docRoot}tools/performance/systrace/index.html">
18    Systrace Walkthrough</a></li>
19</ul>
20
21</div>
22
23  <p>This walkthrough shows the basic usage and workflow for the Batterystats tool and the Battery
24  Historian script.</p>
25
26  <p>Batterystats collects battery data from your device, and Battery Historian converts that data
27  into an HTML visualization that you can view in your Browser. Batterystats is part of the Android
28  framework, and Battery Historian is open-sourced and available on GitHub at <a href=
29  "https://github.com/google/battery-historian">https://github.com/google/battery-historian</a>.</p>
30
31  <p>What it's good for:</p>
32
33  <ul>
34    <li>Showing you where and how processes are drawing current from the battery.</li>
35
36    <li>Identifying tasks in your app that could be deferred or even removed to improve battery
37    life.</li>
38  </ul>
39
40  <h2>Prerequisites</h2>
41
42  <ul>
43    <li>A mobile device with <a href=
44    "http://developer.android.com/tools/device.html#developer-device-options">Developer Options</a>
45    enabled running Android 5.0 or higher.</li>
46  </ul>
47
48  <h2>Working with Batterystats &amp; Battery Historian</h2>
49
50  <div class="sidebox-wrapper" style="width:400px;">
51      <div class="sidebox" style="width:350px;">
52        <h2>Summary</h2>
53          <code>
54            <p><b>https://github.com/google/battery-historian</b></p>
55            <p>&gt; adb kill-server</p>
56            <p>&gt; adb devices</p>
57            <p>&gt; adb shell dumpsys batterystats --reset</p>
58            <p>&lt;disconnect and play with app&gt;...&lt;reconnect&gt;</p>
59            <p>&gt; adb devices</p>
60            <p>&gt;adb shell dumpsys batterystats &gt; batterystats.txt</p>
61            <p>&gt; python historian.py batterystats.txt &gt; batterystats.html</p>
62          </code>
63      </div>
64  </div>
65
66  <ol>
67
68    <li>Download the open-source Battery Historion Python script from GitHub (<a href=
69    "https://github.com/google/battery-historian">https://github.com/google/battery-historian</a>).
70    </li>
71
72    <li>Unzip the file to extract the Battery Historian folder. Inside the folder,
73      find the <code>historian.py</code> file
74      and move it to the Desktop or another <em>writable</em> directory.</li>
75
76    <li>Connect your mobile device to your computer.</li>
77
78    <li>On your computer, open a Terminal window.</li>
79
80    <li>Change to the directory where you've saved <code>historian.py</code>,
81      <br>for example:
82      <code>cd ~/Desktop</code></li>
83
84    <li>Shut down your running adb server.
85      <br><code>&gt; adb kill-server</code></li>
86
87    <li>Restart adb and check for connected devices.
88      <br><code>&gt; adb devices</code>
89      <br><img src="{@docRoot}images/tools/performance/batterystats-battery-historian/gettingstarted_image01.png">
90      <br>If you don't see any devices, make sure your phone is connected, and USB Debugging
91      is turned on, and then kill and restart adb.</li>
92
93    <li>Reset battery data gathering.
94      <br><code>&gt; adb shell dumpsys batterystats --reset</code>
95      <p>Resetting erases old battery collection data; otherewise, the output will be huge.</p>
96    </li>
97
98    <li>Disconnect your device from your computer so that you are only drawing current from the
99    device's battery.</li>
100
101    <li>Play with your app for a short time.</li>
102
103    <li>Reconnect your phone.</li>
104
105    <li>Make sure your phone is recognized: <code>&gt; adb devices</code></li>
106
107    <li>Dump all battery data. This can take a while:
108      <br><code>&gt; adb shell dumpsys batterystats &gt; batterystats.txt</code></li>
109
110    <li>Create a HTML version of the data dump for Battery Historian:
111       <br><code>&gt; python historian.py batterystats.txt &gt; batterystats.html</code></li>
112
113    <li>Open the <code>batterystats.htm</code> file in your browser.</li>
114
115    <li>Continue with <a href="{@docRoot}tools/performance/batterystats-battery-historian/charts.html">
116        Battery Historian Charts</a>.
117    </li>
118
119    <div class="figure" style="">
120      <img src="{@docRoot}images/tools/performance/batterystats-battery-historian/gettingstarted_image02.png"
121         alt=""
122      <p class="img-caption">
123        <strong>Figure 1. </strong>Battery Historian output.
124      </p>
125    </div>
126  </ol>
127
128
129
130