Batterystats와 Battery Historian을 사용하여 배터리 사용량 프로파일링
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이 문서에서는 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 페이지에 있는 리드미를 참고하세요. Docker를 사용하여 설치하려면 다음 단계를 따르세요.
Docker 웹사이트의 안내에 따라 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
Battery Historian 이미지를 실행하기 전에 Docker의 GUI 프런트엔드인 Docker 데스크톱 앱을 실행합니다. 이를 실행하면 Docker 도구가 초기화됩니다. Battery Historian은 한 번 이상 이 작업을 실행할 때까지 실행되지 않습니다.
Battery Historian을 처음 실행할 때 명령줄에서 Battery Historian을 실행합니다. Docker 데스크톱 앱에서는 웹 서버를 실행할 포트를 지정할 수 없습니다. 이 작업은 명령줄에서만 가능합니다. 그러나 명령줄에서 컨테이너를 성공적으로 실행하고 나면 Docker 데스크톱에 항목이 생성되므로 Docker 데스크톱에서 동일한 리스너 포트를 사용하여 이를 실행할 수 있습니다.
다음 명령어를 사용하여 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 연결을 해제하고 데이터를 클라우드로 보냅니다.
선택적 경로 인수를 사용하여 지정한 디렉터리에 batterystats.txt 파일을 만듭니다. 경로를 지정하지 않으면 파일이 홈 디렉터리에 만들어집니다.
원시 데이터에서 보고서를 만듭니다.
Android 7.0 이상을 실행하는 기기의 경우:
adb bugreport [path/]bugreport.zip
Android 6.0 이상을 실행하는 기기의 경우:
adb bugreport [path/]bugreport.txt
Bugreport를 완료하는 데 몇 분 정도 걸릴 수 있습니다. 완료될 때까지 기기의 연결을 끊거나 프로세스를 취소하지 마세요.
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에서 실행됩니다.
찾아보기를 클릭한 다음 위에서 만든 bugreport 파일을 선택합니다.
제출을 클릭합니다. Batterystats 데이터에서 생성된 차트가 Battery Historian에 열립니다.
Battery Historian 차트를 사용하여 데이터 보기
Battery Historian 차트는 시간 경과에 따른 전력 관련 이벤트를 그래프로 표시합니다.
시스템 구성요소가 활성화되어 배터리에서 전류를 유입하는 경우 각 행에 색상이 지정된 막대 세그먼트가 표시됩니다. 이 차트에는 구성요소에서 사용하는 배터리의 양은 표시되지 않으며 앱의 활성 여부만 표시됩니다. 차트는 카테고리별로 구성되며, 차트의 x축에 표시된 것과 같이 시간 경과에 따른 각 카테고리의 막대가 표시됩니다.
그림 3. Battery Historian 차트 예
드롭다운 목록에서 추가 측정항목을 선택합니다.
측정항목 이름 위에 포인터를 가져가면 차트에서 사용된 색상의 키를 포함하여 각 측정항목에 관한 자세한 내용을 볼 수 있습니다.
막대 위로 포인터를 가져가면 측정항목에 관한 자세한 정보와 특정 시점의 배터리 통계를 볼 수 있습니다.
추가 Batterystats 출력
Battery Historian 차트 뒤의 통계 섹션에 있는 batterystats.txt 파일에서 추가 정보를 볼 수 있습니다.
그림 4. Battery Historian의 통계 섹션
1System Stats 탭에는 셀 신호 수준 및 화면 밝기와 같은 시스템 전체 통계가 포함되어 있습니다. 이 정보는 기기에서 발생하는 전반적인 상황을 알려 주며 외부 이벤트가 테스트에 영향을 미치지 않는지 확인하는 데 특히 유용합니다.
2App Stats 탭에는 특정 앱과 관련된 정보가 포함되어 있습니다. App Selection 창의 3Sort apps by 드롭다운 목록을 사용하여 앱 목록을 정렬합니다. 4 앱 드롭다운 목록을 사용하여, 통계를 볼 특정 앱을 선택할 수 있습니다.
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-07-27(UTC)
[null,null,["최종 업데이트: 2025-07-27(UTC)"],[],[],null,["# Profile battery usage with Batterystats and Battery Historian\n\n| **Warning:** Battery Historian is no longer actively maintained; if possible, consider using [system tracing](/topic/performance/tracing), the [Macrobenchmark power metric](/topic/performance/benchmarking/macrobenchmark-metrics#power), or the [Power Profiler](/studio/profile/power-profiler) to get insights into battery performance.\n\nThis document shows the basic setup steps and workflow for the Batterystats tool\nand the Battery Historian script. To learn how to use Battery Historian to\ninspect battery consumption patterns, see [Analyze power use with Battery\nHistorian](/topic/performance/power/battery-historian).\n\nBatterystats is a tool included in the Android framework that collects battery\ndata on your device. You can use [`adb`](/studio/command-line/adb) to dump the\ncollected battery data to your development machine and create a report you can\nanalyze using Battery Historian. Battery Historian converts the report from\nBatterystats into an HTML visualization that you can view in your browser.\n\nBatterystats and Battery Historian are useful for the following:\n\n- Showing you where and how processes are drawing current from the battery.\n- Identifying tasks in your app that can be deferred or removed to improve battery life.\n\n| **Note:** To use Batterystats and Battery Historian, you need a mobile device with [USB debugging](/studio/debug/dev-options) enabled.\n\nInstall Battery Historian\n-------------------------\n\nYou can use Docker to install Battery Historian. For alternative installation\nmethods, including building from source, see the\n[README](https://github.com/google/battery-historian) on the\nproject's GitHub page. To install using Docker, do the following:\n\n1. Install Docker by following the instructions on the\n [Docker website](https://docs.docker.com/desktop). Any\n [subscription](https://docker.com/pricing) type works,\n including a free Personal subscription.\n\n2. To confirm Docker is correctly installed, open the command line and\n enter the following command:\n\n docker run hello-world\n\n If Docker is correctly installed, it displays an output like this: \n\n Unable to find image 'hello-world:latest' locally\n latest: Pulling from library/hello-world\n 78445dd45222: Pull complete\n Digest:\n sha256:c5515758d4c5e1e838e9cd307f6c6a0d620b5e07e6f927b07d05f6d12a1ac8d7\n Status: Downloaded newer image for hello-world:latest\n\n Hello from Docker!\n This message shows that your installation appears to be working correctly.\n\n To generate this message, Docker took the following steps:\n 1. The Docker client contacted the Docker daemon.\n 2. The Docker daemon pulled the \"hello-world\" image from the Docker Hub.\n 3. The Docker daemon created a new container from that image which runs the\n executable that produces the output you are currently reading.\n 4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal\n\n3. Launch the Docker Desktop app---which is a GUI frontend for Docker---before\n you run the Battery Historian image. Running this initializes the Docker\n tools. Battery Historian doesn't run until you do this at least once.\n\n4. Run Battery Historian from the command line when running it for the first\n time. The Docker Desktop app doesn't let you specify the port to run the web\n server on. You can only do this from the command line. However, after you\n successfully run the container from the command line, an entry is created in\n Docker Desktop, and then you can launch it using the same listener port\n from Docker Desktop.\n\n5. Run the Battery Historian image using the following command:\n\n ```\n docker run -p port_number:9999 gcr.io/android-battery-historian/stable:3.1 --port 9999\n ```\n\n Battery Historian uses the port of your choice, as specified using\n \u003cvar translate=\"no\"\u003eport_number\u003c/var\u003e.\n | **Note:** If you're using a Windows machine, you might need to enable virtualization in your BIOS. Check the documentation for your motherboard for more information about how to enable virtualization. If you can run the [Android Emulator](/studio/run/emulator), then virtualization is already enabled.\n6. Navigate to Battery Historian in your browser to confirm it's running. The\n address varies depending on your operating system:\n\n For Linux and Mac\n : Battery Historian is available at\n `http://localhost:`\u003cvar translate=\"no\"\u003eport_number\u003c/var\u003e.\n\n For Windows\n : After you start Docker, it tells you the IP address of the machine it\n is using. For example, if the IP address is 123.456.78.90, Battery\n Historian is available at\n `http://123.456.78.90:`\u003cvar translate=\"no\"\u003eport_number\u003c/var\u003e.\n\n \u003cbr /\u003e\n\n It then displays the Battery Historian start page, where you can upload and\n view battery statistics.\n **Figure 1.** The start page for Battery Historian.\n\nGather data with Batterystats\n-----------------------------\n\nTo collect data from your device using Batterystats and open it in Battery\nHistorian, do the following:\n\n1. Connect your mobile device to your computer.\n\n2. From a Terminal window, shut down your running `adb` server by running the\n following command:\n\n adb kill-server\n\n3. Restart `adb` and check for connected devices by running the following\n command.\n\n adb devices\n\n It lists your device, similar to the following example output.\n **Figure 2.** The output of `adb devices`, showing one connected device\n\n If it doesn't list any devices, make sure your phone is connected and [USB\n debugging](/studio/debug/dev-options#Enable-debugging) is enabled, and then\n stop and restart `adb`.\n4. Reset battery data gathering by running the following command:\n\n adb shell dumpsys batterystats --reset\n\n The device is always collecting Batterystats and other debugging information\n in the background. Resetting erases previous battery collection data. If you\n don't reset, the output can be very large.\n5. Disconnect your device from your computer so that you are only drawing\n current from the device's battery.\n\n6. Use your app and perform actions for which you want to collect data for. For\n example, disconnect from Wi-Fi and send data to the cloud.\n\n7. Reconnect your phone.\n\n8. Make sure your phone is recognized and run the following command:\n\n adb devices\n\n9. Dump all battery data by running the following command. This can take a\n while.\n\n ```\n adb shell dumpsys batterystats \u003e [path/]batterystats.txt\n ```\n\n The `batterystats.txt` file is created in the directory you specify using\n the optional path argument. If you don't specify a path, the file is\n created in your home directory.\n10. Create a report from raw data.\n\n For devices running Android 7.0 and higher:\n :\n\n ```\n adb bugreport [path/]bugreport.zip\n ```\n\n For devices running Android 6.0 and lower:\n :\n\n ```\n adb bugreport [path/]bugreport.txt\n ```\n\n \u003cbr /\u003e\n\n Bugreport can take several minutes to complete. Don't disconnect your\n device or cancel the process until it's complete.\n\n As with `batterystats.txt`, these files are created in the directory you\n specify using the optional \u003cvar translate=\"no\"\u003epath\u003c/var\u003e argument. If you\n don't specify a path, they are created in your home directory.\n\n If it's not already running, run Battery Historian using the following\n command: \n\n ```\n docker run -p port_number:9999 gcr.io/android-battery-historian/stable:3.1 --port 9999\n ```\n11. To view your data in Battery Historian, open the Battery Historian in your\n browser. For Mac and Linux, Battery Historian runs at\n `http://localhost:`\u003cvar translate=\"no\"\u003eport_number\u003c/var\u003e. For Windows, Battery\n Historian runs at\n `http://`\u003cvar translate=\"no\"\u003eyour_IP_address\u003c/var\u003e`:`\u003cvar translate=\"no\"\u003eport_number\u003c/var\u003e.\n\n12. Click **Browse** and then choose the bugreport file you created.\n\n13. Click **Submit**. Battery Historian opens a chart created from your\n Batterystats data.\n\nView data with Battery Historian charts\n---------------------------------------\n\nThe Battery Historian chart graphs power-relevant events over time.\n\nEach row shows a colored bar segment when a system component is active and thus\ndrawing current from the battery. The chart doesn't show how much battery is\nused by the component---only whether the app is active. Charts are organized by\ncategory, showing a bar for each category over time, as displayed on the\n*x*-axis of the chart.\n**Figure 3.** Example of a Battery Historian chart.\n\n1. Add additional metrics from the drop-down list.\n2. Hold the pointer over the metric name to see more information about each metric, including a key for the colors used in the chart.\n3. Hold the pointer over a bar to see more detailed information about that metric and the battery stats at a specific point on the timeline.\n\nAdditional Batterystats output\n------------------------------\n\nYou can view additional information from the `batterystats.txt` file in the\nstats section after the Battery Historian chart.\n**Figure 4.** The stats section of Battery Historian.\n\nThe 1 **System Stats** tab includes system-wide\nstatistics, such as cell signal levels and screen brightness. This information\nprovides an overall picture of what's happening with the device. This is\nespecially useful to make sure no external events are affecting your test.\n\nThe 2 **App Stats** tab includes information about\nspecific apps. Sort the list of apps using the 3\n**Sort apps by** drop-down list in the **App Selection** pane. You\ncan select a specific app to view stats for using the\n4 apps drop-down list."]]
