{"id":13537435,"url":"https://github.com/google/battery-historian","last_synced_at":"2025-12-17T00:29:05.075Z","repository":{"id":18021980,"uuid":"21052985","full_name":"google/battery-historian","owner":"google","description":"Battery Historian is a tool to analyze battery consumers using Android \"bugreport\" files.","archived":true,"fork":false,"pushed_at":"2019-07-15T16:25:16.000Z","size":4402,"stargazers_count":5364,"open_issues_count":148,"forks_count":971,"subscribers_count":269,"default_branch":"master","last_synced_at":"2025-09-26T03:36:25.544Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-06-20T21:28:26.000Z","updated_at":"2025-09-24T10:37:30.000Z","dependencies_parsed_at":"2022-07-12T15:14:45.572Z","dependency_job_id":null,"html_url":"https://github.com/google/battery-historian","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/google/battery-historian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fbattery-historian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fbattery-historian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fbattery-historian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fbattery-historian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google","download_url":"https://codeload.github.com/google/battery-historian/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fbattery-historian/sbom","scorecard":{"id":436434,"data":{"date":"2025-08-11","repo":{"name":"github.com/google/battery-historian","commit":"d2356ba4fd5f69a631fdf766b2f23494b50f6744"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.9,"checks":[{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Maintained","score":0,"reason":"project is archived","details":["Warn: Repository is archived."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Code-Review","score":0,"reason":"Found 0/22 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"License","score":9,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Warn: project license file does not contain an FSF or OSI license."],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: github.com/google/.github/SECURITY.md:1","Info: Found linked content: github.com/google/.github/SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: github.com/google/.github/SECURITY.md:1","Info: Found text in security policy: github.com/google/.github/SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}}]},"last_synced_at":"2025-08-19T04:47:12.905Z","repository_id":18021980,"created_at":"2025-08-19T04:47:12.905Z","updated_at":"2025-08-19T04:47:12.905Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277181036,"owners_count":25774846,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-27T02:00:08.978Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T09:00:59.042Z","updated_at":"2025-09-29T02:31:55.707Z","avatar_url":"https://github.com/google.png","language":"Go","funding_links":[],"categories":["Go","Tools"],"sub_categories":["Postfix code completion"],"readme":"# Battery Historian\n\nBattery Historian is a tool to inspect battery related information and events on an Android device running Android 5.0 Lollipop (API level 21) and later, while the device was not plugged in. It allows application developers to visualize system and application level events on a timeline with panning and zooming functionality, easily see various aggregated statistics since the device was last fully charged, and select an application and inspect the metrics that impact battery specific to the chosen application. It also allows an A/B comparison of two bugreports, highlighting differences in key battery related metrics.\n\n## Getting Started\n\n#### Using Docker\n\nInstall [Docker](\u003chttps://docs.docker.com/engine/installation/\u003e).\n\nRun the Battery Historian image. Choose a port number and replace `\u003cport\u003e` with\nthat number in the commands below:\n\n```\ndocker -- run -p \u003cport\u003e:9999 gcr.io/android-battery-historian/stable:3.0 --port 9999\n```\n\nFor Linux and Mac OS X:\n\n* That's it, you're done! Historian will be available at\n  `http://localhost:\u003cport\u003e`.\n\nFor Windows:\n\n* You may have to [enable Virtualization in your\n  BIOS](\u003chttp://www.itworld.com/article/2981515/virtualization/virtualbox-diagnose-and-fix-vt-xamd-v-hardware-acceleration-errors.html\u003e).\n\n* Once you start Docker, it should tell you the IP address of the machine it is\nusing. If, for example, the IP address is 123.456.78.90, Historian will be\navailable at `http://123.456.78.90:\u003cport\u003e`.\n\nFor more information about the port forwarding, see the [Docker\ndocumentation](\u003chttps://docs.docker.com/engine/reference/run/#/expose-incoming-ports\u003e).\n\n#### Building from source code\n\nMake sure you have at least Golang version 1.8.1:\n\n* Follow the instructions available at \u003chttp://golang.org/doc/install\u003e for downloading and installing the Go compilers, tools, and libraries.\n* Create a workspace directory according to the instructions at\n  \u003chttp://golang.org/doc/code.html#Organization\u003e.\n* Ensure that `GOPATH` and `GOBIN` environment variables are appropriately set and added to your `$PATH`\n  environment variable. `$GOBIN should be set to $GOPATH/bin`.\n  * For Windows, you may set environment variables through the \"Environment Variables\" button on the\n  \"Advanced\" tab of the \"System\" control panel. Some versions of Windows provide this control panel\n  through the \"Advanced System Settings\" option inside the \"System\" control panel.\n  * For Linux and Mac OS X, you can add the following lines to your ~/.bashrc or\n    ~/.profile files (assuming your workspace is $HOME/work):\n\n      ```\n      export GOPATH=$HOME/work\n      export GOBIN=$GOPATH/bin\n      export PATH=$PATH:$GOBIN\n      ```\n\nNext, install Git from \u003chttps://git-scm.com/downloads\u003e if it's not already installed.\n\nNext, make sure Python 2.7 (NOT Python 3!) is installed. See \u003chttps://python.org/downloads\u003e\nif it isn't, and ensure that python is added to your `$PATH` environment variable.\n\nNext, install Java from \u003chttp://www.oracle.com/technetwork/java/javase/downloads/index.html\u003e.\n\nNext, download the Battery Historian code and its dependencies:\n\n```\n$ go get -d -u github.com/google/battery-historian/...\n```\n\nFinally, run Battery Historian!\n\n```\n$ cd $GOPATH/src/github.com/google/battery-historian\n\n# Compile Javascript files using the Closure compiler\n$ go run setup.go\n\n# Run Historian on your machine (make sure $PATH contains $GOBIN)\n$ go run cmd/battery-historian/battery-historian.go [--port \u003cdefault:9999\u003e]\n```\n\nRemember, you must always run battery-historian from inside the `$GOPATH/src/github.com/google/battery-historian` directory:\n\n```\ncd $GOPATH/src/github.com/google/battery-historian\ngo run cmd/battery-historian/battery-historian.go [--port \u003cdefault:9999\u003e]\n```\n\n\n#### How to take a bug report\n\nTo take a bug report from your Android device, you will need to enable USB debugging under `Settings \u003e System \u003e Developer Options`. On Android 4.2 and higher, the Developer options screen is hidden by default. You can enable this by following the instructions [here](\u003chttp://developer.android.com/tools/help/adb.html#Enabling\u003e).\n\nTo obtain a bug report from your development device running Android 7.0 and\nhigher:\n\n```\n$ adb bugreport bugreport.zip\n```\n\nFor devices 6.0 and lower:\n\n```\n$ adb bugreport \u003e bugreport.txt\n```\n\n### Start analyzing!\n\nYou are all set now. Run `historian` and visit \u003chttp://localhost:9999\u003e and\nupload the `bugreport.txt` file to start analyzing.\n\n## Screenshots\n\n##### Timeline:\n\n![Timeline](/screenshots/timeline.png \"Timeline Visualization\")\n\n##### System stats:\n\n![System](/screenshots/system.png \"Aggregated System statistics since the device was last fully charged\")\n\n##### App stats:\n\n![App](/screenshots/app.png \"Application specific statistics\")\n\n## Advanced\n\nTo reset aggregated battery stats and history:\n\n```\nadb shell dumpsys batterystats --reset\n```\n\n##### Wakelock analysis\n\nBy default, Android does not record timestamps for application-specific\nuserspace wakelock transitions even though aggregate statistics are maintained\non a running basis. If you want Historian to display detailed information about\neach individual wakelock on the timeline, you should enable full wakelock\nreporting using the following command before starting your experiment:\n\n```\nadb shell dumpsys batterystats --enable full-wake-history\n```\n\nNote that by enabling full wakelock reporting the battery history log overflows\nin a few hours. Use this option for short test runs (3-4 hrs).\n\n##### Kernel trace analysis\n\nTo generate a trace file which logs kernel wakeup source and kernel wakelock\nactivities:\n\nFirst, connect the device to the desktop/laptop and enable kernel trace logging:\n\n```\n$ adb root\n$ adb shell\n\n# Set the events to trace.\n$ echo \"power:wakeup_source_activate\" \u003e\u003e /d/tracing/set_event\n$ echo \"power:wakeup_source_deactivate\" \u003e\u003e /d/tracing/set_event\n\n# The default trace size for most devices is 1MB, which is relatively low and might cause the logs to overflow.\n# 8MB to 10MB should be a decent size for 5-6 hours of logging.\n\n$ echo 8192 \u003e /d/tracing/buffer_size_kb\n\n$ echo 1 \u003e /d/tracing/tracing_on\n```\n\nThen, use the device for intended test case.\n\nFinally, extract the logs:\n\n```\n$ echo 0 \u003e /d/tracing/tracing_on\n$ adb pull /d/tracing/trace \u003csome path\u003e\n\n# Take a bug report at this time.\n$ adb bugreport \u003e bugreport.txt\n```\n\nNote:\n\nHistorian plots and relates events in real time (PST or UTC), whereas kernel\ntrace files logs events in jiffies (seconds since boot time). In order to relate\nthese events there is a script which approximates the jiffies to utc time. The\nscript reads the UTC times logged in the dmesg when the system suspends and\nresumes. The scope of the script is limited to the amount of timestamps present\nin the dmesg. Since the script uses the dmesg log when the system suspends,\nthere are different scripts for each device, with the only difference being\nthe device-specific dmesg log it tries to find. These scripts have been\nintegrated into the Battery Historian tool itself.\n\n##### Power monitor analysis\n\nLines in power monitor files should have one of the following formats, and the\nformat should be consistent throughout the entire file:\n\n```\n\u003ctimestamp in epoch seconds, with a fractional component\u003e \u003camps\u003e \u003coptional_volts\u003e\n```\n\nOR\n\n```\n\u003ctimestamp in epoch milliseconds\u003e \u003cmilliamps\u003e \u003coptional_millivolts\u003e\n```\n\nEntries from the power monitor file will be overlaid on top of the timeline\nplot.\n\nTo ensure the power monitor and bug report timelines are somewhat aligned,\nplease reset the batterystats before running any power monitor logging:\n\n```\nadb shell dumpsys batterystats --reset\n```\n\nAnd take a bug report soon after stopping power monitor logging.\n\nIf using a Monsoon:\n\nDownload the AOSP Monsoon Python script from \u003chttps://android.googlesource.com/platform/cts/+/master/tools/utils/monsoon.py\u003e\n\n```\n# Run the script.\n$ monsoon.py --serialno 2294 --hz 1 --samples 100000 -timestamp | tee monsoon.out\n\n# ...let device run a while...\n\n$ stop monsoon.py\n```\n\n##### Modifying the proto files\n\nIf you want to modify the proto files (pb/\\*/\\*.proto), first download the\nadditional tools necessary:\n\nInstall the standard C++ implementation of protocol buffers from \u003chttps://github.com/google/protobuf/blob/master/src/README.md\u003e\n\nDownload the Go proto compiler:\n\n```\n$ go get -u github.com/golang/protobuf/protoc-gen-go\n```\n\nThe compiler plugin, protoc-gen-go, will be installed in $GOBIN, which must be\nin your $PATH for the protocol compiler, protoc, to find it.\n\nMake your changes to the proto files.\n\nFinally, regenerate the compiled Go proto output files using `regen_proto.sh`.\n\n##### Other command line tools\n\n```\n# System stats\n$ go run cmd/checkin-parse/local_checkin_parse.go --input=bugreport.txt\n\n# Timeline analysis\n$ go run cmd/history-parse/local_history_parse.go --summary=totalTime --input=bugreport.txt\n\n# Diff two bug reports\n$ go run cmd/checkin-delta/local_checkin_delta.go --input=bugreport_1.txt,bugreport_2.txt\n```\n\n\n## Support\n\n- G+ Community (Discussion Thread: Battery Historian): https://plus.google.com/b/108967384991768947849/communities/114791428968349268860\n\nIf you've found an error in this project, please file an issue:\n\u003chttps://github.com/google/battery-historian/issues\u003e\n\n## License\n\nCopyright 2016 Google, Inc.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n  \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT\nWARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the\nLicense for the specific language governing permissions and limitations under\nthe License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fbattery-historian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle%2Fbattery-historian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fbattery-historian/lists"}