在這份文件中，我們將介紹 Batterystats 工具與 Battery Historian 指令碼的基本設定步驟和工作流程。如要瞭解如何使用 Battery Historian 檢查電池耗電模式，請參閱「使用 Battery Historian 分析電力使用情形」。
Batterystats 是 Android 架構中的一項工具，可收集裝置中的電池資料。您可以利用 adb 將收集到的電池資料轉儲到開發機器，然後建立可透過 Battery Historian 分析的報表。Battery Historian 會將報表從 Batterystats 轉換成 HTML 圖表，方便您在瀏覽器中查看。
Batterystats 和 Battery Historian 很適合用於以下用途：
- 瞭解程序中消耗電池電力的環節和方式。
- 找出應用程式中可延遲或移除的工作，以提升電池續航力。
安裝 Battery Historian
您可以使用 Docker 安裝 Battery Historian。其他安裝方式 (包括透過原始碼建構) 請見專案 GitHub 頁面中的 README 檔案。如要透過 Docker 安裝，請按照下列步驟操作：
如要確認 Docker 是否已正確安裝，請開啟指令列並輸入下列指令：
docker run hello-world如果已正確安裝 Docker，您會看到如下的輸出內容：
Unable to find image 'hello-world:latest' locally latest: Pulling from library/hello-world 78445dd45222: Pull complete Digest: sha256:c5515758d4c5e1e838e9cd307f6c6a0d620b5e07e6f927b07d05f6d12a1ac8d7 Status: Downloaded newer image for hello-world:latest Hello from Docker! This message shows that your installation appears to be working correctly. To generate this message, Docker took the following steps: 1. The Docker client contacted the Docker daemon. 2. The Docker daemon pulled the "hello-world" image from the Docker Hub. 3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading. 4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal請先啟動 Docker Desktop 應用程式 (即 Docker 的 GUI 前端)，再執行 Battery Historian 映像檔。執行這個映像檔會將 Docker 工具初始化。這個步驟必須至少執行一次，Battery Historian 才能運作。
第一次執行 Battery Historian 時，請從指令列執行此工具。您無法透過 Docker Desktop 應用程式指定要執行網路伺服器的通訊埠，只能透過指令列執行此操作。不過，當您成功從指令列執行容器後，系統會在 Docker Desktop 中建立一個項目，而您可以從 Docker Desktop 中使用同一組事件監聽器通訊埠啟動該項目。
使用下列指令執行 Battery Historian 映像檔：
docker run -p port_number:9999 gcr.io/android-battery-historian/stable:3.1 --port 9999
Battery Historian 會使用您選擇的通訊埠，像是透過
port_number指定的通訊埠。在瀏覽器中前往 Battery Historian 頁面，確認該工具正在執行。相關位址會因您的作業系統而異：
- Linux 和 Mac
- Battery Historian 的位址是
http://localhost:port_number。 - Windows
- 啟動 Docker 後，系統會指出此工具所用電腦的 IP 位址。舉例來說，如果 IP 位址是 123.456.78.90，代表您可以前往
http://123.456.78.90:port_number存取 Battery Historian。
隨後，Battery Historian 的起始網頁將會開啟，您可以在這裡上傳及查看電池統計資料。
圖 1. Battery Historian 的起始網頁。
使用 Batterystats 收集資料
如要使用 Batterystats 從裝置收集資料，然後在 Battery Historian 中開啟，請執行以下操作：
將行動裝置連接到電腦。
在終端機視窗中執行下列指令，關閉執行中的
adb伺服器：adb kill-server重新啟動
adb並執行下列指令，檢查是否有任何已連結的裝置。adb devices這項指令會列出您的裝置，類似於以下範例的輸出內容。
圖 2. adb devices的輸出內容，顯示有一部連接的裝置。如果指令未列出任何裝置，請確認手機已經連接，且已開啟 USB 偵錯功能，然後終止並重新啟動
adb。執行以下指令，重設電池資料的收集作業：
adb shell dumpsys batterystats --reset裝置一律會在背景收集 Batterystats 和其他偵錯資訊。當您選擇重設之後，系統會清除先前收集的電池資料。如果您不想重設，輸出內容會非常龐大。
中斷裝置與電腦的連結，讓裝置只能從本身的電池取得電力。
使用應用程式，然後執行您想收集資料的操作，例如中斷 Wi-Fi 連線，並將資料傳送至雲端。
重新連接手機。
確認系統可辨識您的手機後，執行下列指令：
adb devices執行下列指令，轉儲所有電池資料。這可能需要一段時間。
adb shell dumpsys batterystats > [path/]batterystats.txt
系統會使用選用路徑引數，在您指定的目錄中建立
batterystats.txt檔案。如果您未指定路徑，檔案會建立在主目錄中。使用原始資料建立報表。
- 搭載 Android 7.0 以上版本的裝置：
-
adb bugreport [path/]bugreport.zip
- 搭載 Android 6.0 以下版本的裝置：
-
adb bugreport [path/]bugreport.txt
錯誤報告可能需要幾分鐘才能製作完成。在此之前，請勿中斷裝置連結或取消程序。
和
batterystats.txt相同，系統會使用選用的path引數，在您指定的目錄中建立這些檔案。如果您未指定路徑，這些檔案會建立在主目錄中。如果 Battery Historian 尚未執行，請使用以下指令執行此工具：
docker run -p port_number:9999 gcr.io/android-battery-historian/stable:3.1 --port 9999
如要在 Battery Historian 中檢視資料，請在瀏覽器中開啟 Battery Historian。在 Mac 和 Linux，Battery Historian 會在
http://localhost:port_number執行；如果是 Windows，Battery Historian 則在http://your_IP_address:port_number執行。按一下「Browse」，然後選擇您建立的錯誤報告檔案。
按一下「Submit」，Battery Historian 會開啟依據 Batterystats 資料建立的圖表。
使用 Battery Historian 圖表檢視資料
Battery Historian 會以圖表的方式顯示一段時間內的電力相關事件。
當系統元件因處於使用狀態而消耗電池電力時，圖表中的每一列都會顯示彩色的長條區段。此圖表不會顯示元件已使用多少電力，只會顯示應用程式是否處於啟用狀態。系統會按照類別來整理圖表，並以長條圖顯示各類別的長期變化，如圖表的 x 軸所示。
- 從下拉式清單新增其他指標。
- 將游標懸停在指標名稱上，即可查看每個指標的詳細資訊，包括圖表中所用顏色的圖例說明。
- 將游標懸停在長條上，即可查看該指標的詳細資訊，以及時間軸上特定時間點的電池統計資料。
其他 Batterystats 輸出內容
在 Battery Historian 圖表之後的統計資料部分中，您可以查看 batterystats.txt 檔案的其他相關資訊。
1「System Stats」分頁包含整個系統的統計資料，例如電池信號等級和螢幕亮度。此資訊可有助於您全面掌握裝置的運作情況，如要確保沒有外部事件影響您的測試，這就特別有用。
2「App Stats」分頁包含特定應用程式的資訊。請使用「App Selection」窗格中的「Sort apps by」下拉式選單 (3) 排序應用程式清單。您可以使用應用程式下拉式選單 (4)，選取要查看哪個特定應用程式的統計資料。