{"id":28406880,"url":"https://github.com/powerapi-ng/joulehunter","last_synced_at":"2025-06-29T09:31:43.951Z","repository":{"id":37415066,"uuid":"406745757","full_name":"powerapi-ng/joulehunter","owner":"powerapi-ng","description":"Joulehunter helps you find what part of your code is consuming considerable amounts of energy.","archived":false,"fork":false,"pushed_at":"2022-11-02T17:02:05.000Z","size":2693,"stargazers_count":11,"open_issues_count":4,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-02T08:19:33.021Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/powerapi-ng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-09-15T12:02:27.000Z","updated_at":"2025-03-02T17:16:40.000Z","dependencies_parsed_at":"2025-04-13T10:50:00.146Z","dependency_job_id":null,"html_url":"https://github.com/powerapi-ng/joulehunter","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/powerapi-ng/joulehunter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/powerapi-ng%2Fjoulehunter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/powerapi-ng%2Fjoulehunter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/powerapi-ng%2Fjoulehunter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/powerapi-ng%2Fjoulehunter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/powerapi-ng","download_url":"https://codeload.github.com/powerapi-ng/joulehunter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/powerapi-ng%2Fjoulehunter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262569503,"owners_count":23330231,"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","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":"2025-06-01T23:10:27.300Z","updated_at":"2025-06-29T09:31:43.935Z","avatar_url":"https://github.com/powerapi-ng.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"joulehunter \n=========== \n[![Unit tests](https://github.com/powerapi-ng/joulehunter/actions/workflows/test.yaml/badge.svg)](https://github.com/powerapi-ng/joulehunter/actions/workflows/test.yaml)\n[![PyPI version](https://badge.fury.io/py/joulehunter.svg)](https://badge.fury.io/py/joulehunter)\n![screenshot](https://user-images.githubusercontent.com/11022568/134655797-3872379e-0e4e-48d6-a771-6a94c756fa67.png)\n\nJoulehunter helps you find what part of your code is consuming considerable amounts of energy.\n\nThis repo is still a work in progress. 😄\n\nCompatibility\n------------\n\nJoulehunter runs on **Linux** machines with **Intel RAPL** support. This technology has been available since the Sandy Bridge generation.\n\n\nInstallation\n------------\n\nYou can install joulehunter with pip: ```pip install joulehunter```.\n\nYou can also clone the repo and install it directly:\n\n     git clone https://github.com/powerapi-ng/joulehunter.git\n     cd joulehunter\n     python setup.py install\n\nUsage\n------------\n\nJoulehunter works similarly to [pyinstrument](https://github.com/joerick/pyinstrument), as we forked the repo and replaced time measuring with energy measuring. Here's [pyinstrument's documentation](https://pyinstrument.readthedocs.io/). Whenever ```pyinstrument``` is present in a variable name, it should be replaced with ```joulehunter``` (for example, ```PYINSTRUMENT_PROFILE_DIR``` turns into ```JOULEHUNTER_PROFILE_DIR```).\n\n### Command line\n\n```joulehunter -l``` will list the available domains on this machine. These include the packages and their components, such as the DRAM and core.\n\nThe command ```joulehunter main.py``` will execute ```main.py``` and measure the energy consumption of the first package (CPU).\n\nTo select the package to analyze use the option ```-p``` or ```--package``` followed by the package number or the package name. The default value is 0.\n\nThe options ```-c``` and ```--component``` allow you to measure the energy of an individual component by specifying their name or ID. If not specified, the entire package will be selected.\n\n\n#### Example\n\nExecuting ```joulehunter -l``` could output this:\n    \n    [0] package-0\n      [0] core\n      [1] uncore\n      [2] dram\n    [1] package-1\n      [0] core\n      [1] uncore\n      [2] dram\n\nIf we run ```joulehunter -p package-1 -c 2 my_file.py```, joulehunter will execute ```my_file.py``` and measure the energy consumption of package-1's DRAM.\n\n### Profiling chunks of code\n\nAs [pyinstrument's documentation](https://pyinstrument.readthedocs.io/en/latest/guide.html#profile-a-specific-chunk-of-code) shows, it's also possible to profile specific chunks of code.\n\nJoulehunter's Profiler class can receive two additional arguments: ```package``` and ```component```. They receive the ID (as a string or integer) or name of the desired package/component. If ```package``` is not specified, ```package-0``` will be used. If ```component``` is ```None```, the entire package will be analyzed.\n\n### Profiling web requests in Flask\n\nPlease refer to [pyinstrument's documentation](https://pyinstrument.readthedocs.io/en/latest/guide.html#profile-a-web-request-in-flask) for instructions on how to profile web requests in Flask. As in the previous case, joulehunter's ```Profiler()``` accepts two additional arguments.\n\n### Profiling web requests in Django\n\nProfiling web requests in Django as explained in [pyinstrument's documentation](https://pyinstrument.readthedocs.io/en/latest/guide.html#profile-a-web-request-in-django) selects package 0 as the default domain (don't forget to rename the ```pyinstrument``` in variable names with ```joulehunter```).\n\nThe user can choose a particular package and component as follows:\n\n**Query component**: The query strings ```package``` and ```component``` are used to select the desired package and component. For example, including ```?profiler\u0026package=0\u0026component=dram``` at the end of a request URL will select the first package and the DRAM. If the component query component is present but empty, the package will be analyzed.\n\n\n**Variable in ```settings.py```:** The user's selection can also be defined in ```settings.py``` with the ```JOULEHUNTER_PACKAGE``` and ```JOULEHUNTER_COMPONENT``` variables. These are later passed to ```Package()```.\n\nIf the package or component is defined both as a query component and in ```settings.py```, the one defined as a query component will be selected.\n\n\nRead permission\n---------------\n\nDue to a [security vulnerability](https://platypusattack.com), only root has read permission for the energy files. In order to circumvent this, run the script as root or grant read permissions for the following files:\n\n    /sys/devices/virtual/powercap/intel-rapl/intel-rapl:*/energy_uj\n    /sys/devices/virtual/powercap/intel-rapl/intel-rapl:*/intel-rapl:*:*/energy_uj\n    \nMore info [here](https://github.com/powerapi-ng/pyJoules/issues/13).\n\nAcknowledgments\n------------\n\nThanks to [Joe Rickerby](https://github.com/joerick) and all of [pyinstrument](https://github.com/joerick/pyinstrument)'s contributors.\n\nThis fork is being developed by [Chakib Belgaid](https://github.com/chakib-belgaid) and [Alex Kaminetzky](https://github.com/akaminetzkyp). Feel free to ask us any questions!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowerapi-ng%2Fjoulehunter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpowerapi-ng%2Fjoulehunter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowerapi-ng%2Fjoulehunter/lists"}