نمایه استفاده از باتری با Batterystats و Battery Historian
با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
این سند مراحل اولیه راه اندازی و گردش کار ابزار Batterystats و اسکریپت Battery Historian را نشان می دهد. برای یادگیری نحوه استفاده از تاریخچه باتری برای بررسی الگوهای مصرف باتری، به تحلیل مصرف انرژی با تاریخچه باتری مراجعه کنید.
Batterystats ابزاری است که در چارچوب Android گنجانده شده است که داده های باتری دستگاه شما را جمع آوری می کند. می‌توانید از adb استفاده کنید تا داده‌های باتری جمع‌آوری‌شده را به دستگاه توسعه خود منتقل کنید و گزارشی ایجاد کنید که می‌توانید با استفاده از Battery Historian تجزیه و تحلیل کنید. Battery Historian گزارش را از Batterystats به تصویرسازی HTML تبدیل می کند که می توانید در مرورگر خود مشاهده کنید.
Batterystats و Battery Historian برای موارد زیر مفید هستند:
به شما نشان می دهد که کجا و چگونه فرآیندها جریان را از باتری می گیرند.
شناسایی وظایفی در برنامه شما که می‌توانند برای بهبود عمر باتری به تعویق بیفتند یا حذف شوند.
Battery Historian را نصب کنید
برای نصب Battery Historian می توانید از Docker استفاده کنید. برای روش‌های نصب جایگزین، از جمله ساختن از منبع، به README در صفحه 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 Desktop را راه اندازی کنید - که یک رابط رابط کاربری گرافیکی برای Docker است. اجرای این ابزار 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 بروید تا تأیید کنید که در حال اجرا است. آدرس بسته به سیستم عامل شما متفاوت است:
برای لینوکس و مک
تاریخچه باتری در http://localhost: port_number موجود است.
برای ویندوز
پس از راه اندازی Docker، آدرس IP دستگاهی که از آن استفاده می کند را به شما می گوید. برای مثال، اگر آدرس IP 123.456.78.90 باشد، Battery Historian در http://123.456.78.90: port_number .
سپس صفحه شروع Battery Historian را نشان می دهد، جایی که می توانید آمار باتری را آپلود و مشاهده کنید.
شکل 1. صفحه شروع برای تاریخچه باتری.
با 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
با اجرای دستور زیر تمام اطلاعات باتری را تخلیه کنید. این ممکن است کمی طول بکشد.
فایل 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 را در مرورگر خود باز کنید. برای مک و لینوکس، Battery Historian در http://localhost: port_number اجرا می‌شود. برای ویندوز، Battery Historian در http:// your_IP_address : port_number اجرا می شود.
روی Browse کلیک کنید و سپس فایل گزارش اشکالی که ایجاد کرده اید را انتخاب کنید.
روی ارسال کلیک کنید. Battery Historian نموداری را باز می کند که از داده های Batterystats شما ایجاد شده است.
مشاهده داده ها با نمودارهای تاریخچه باتری
نمودار تاریخچه باتری رویدادهای مرتبط با انرژی را در طول زمان نمودار می کند.
هر ردیف یک بخش نوار رنگی را نشان می دهد که یک جزء سیستم فعال است و بنابراین جریان را از باتری می گیرد. نمودار میزان مصرف باتری توسط مؤلفه را نشان نمی دهد - فقط اینکه آیا برنامه فعال است یا خیر. نمودارها بر اساس دسته بندی سازماندهی می شوند و یک نوار برای هر دسته در طول زمان نشان می دهند، همانطور که در محور x نمودار نمایش داده می شود.
شکل 3. نمونه ای از نمودار تاریخچه باتری.
معیارهای اضافی را از لیست کشویی اضافه کنید.
نشانگر را روی نام متریک نگه دارید تا اطلاعات بیشتری در مورد هر معیار، از جمله کلیدی برای رنگ های استفاده شده در نمودار مشاهده کنید.
نشانگر را روی یک نوار نگه دارید تا اطلاعات دقیق‌تری درباره آن معیار و آمار باتری در یک نقطه خاص از خط زمانی مشاهده کنید.
خروجی Batterystats اضافی
می توانید اطلاعات اضافی را از فایل batterystats.txt در بخش آمار بعد از نمودار تاریخچه باتری مشاهده کنید.
شکل 4. بخش آمار Battery Historian.
برگه 1System Stats شامل آمارهای کل سیستم، مانند سطوح سیگنال سلولی و روشنایی صفحه نمایش است. این اطلاعات تصویری کلی از آنچه در دستگاه اتفاق می افتد ارائه می دهد. این به ویژه برای اطمینان از اینکه هیچ رویداد خارجی روی تست شما تأثیر نمی گذارد مفید است.
برگه 2App Stats شامل اطلاعاتی در مورد برنامه های خاص است. لیست برنامه ها را با استفاده از 3مرتب سازی برنامه ها بر اساس لیست کشویی در صفحه انتخاب برنامه مرتب کنید. می توانید یک برنامه خاص را برای مشاهده آمار استفاده از لیست کشویی 4 برنامه انتخاب کنید.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی."],[],[],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."]]
