{"id":32964265,"url":"https://github.com/joular/joularjx","last_synced_at":"2026-01-21T12:06:31.956Z","repository":{"id":44484744,"uuid":"409504874","full_name":"joular/joularjx","owner":"joular","description":"JoularJX is a Java-based agent for software power monitoring at the source code level.","archived":false,"fork":false,"pushed_at":"2025-10-01T08:01:40.000Z","size":1205,"stargazers_count":90,"open_issues_count":5,"forks_count":20,"subscribers_count":4,"default_branch":"develop","last_synced_at":"2026-01-11T07:48:56.910Z","etag":null,"topics":["energy","green","java","joular","joularjx","power","software"],"latest_commit_sha":null,"homepage":"https://www.noureddine.org/research/joular/joularjx","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joular.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-23T08:11:54.000Z","updated_at":"2025-12-09T14:25:03.000Z","dependencies_parsed_at":"2023-02-19T16:00:35.174Z","dependency_job_id":"54933a34-a230-4771-bb81-9a223940cdf6","html_url":"https://github.com/joular/joularjx","commit_stats":{"total_commits":169,"total_committers":12,"mean_commits":"14.083333333333334","dds":0.7455621301775148,"last_synced_commit":"7b2a37a9d7010251ea6b83e697ee53efd137d8a4"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/joular/joularjx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joular%2Fjoularjx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joular%2Fjoularjx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joular%2Fjoularjx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joular%2Fjoularjx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joular","download_url":"https://codeload.github.com/joular/joularjx/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joular%2Fjoularjx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28632781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["energy","green","java","joular","joularjx","power","software"],"created_at":"2025-11-13T02:00:33.834Z","updated_at":"2026-01-21T12:06:31.951Z","avatar_url":"https://github.com/joular.png","language":"Java","funding_links":[],"categories":["Measure power usage by software"],"sub_categories":["GNU/Linux"],"readme":"# \u003ca href=\"https://www.noureddine.org/research/joular/\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/joular/.github/main/profile/joular.png\" alt=\"Joular Project\" width=\"64\" /\u003e\u003c/a\u003e JoularJX :microscope:\r\n\r\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue)](https://www.gnu.org/licenses/gpl-3.0)\r\n[![Java](https://img.shields.io/badge/Made%20with-Java-orange)](https://openjdk.java.net)\r\n\r\n![JoularJX Logo](joularjx.png)\r\n\r\nJoularJX is a Java-based agent for software power monitoring at the source code level.\r\n\r\nDetailed documentation (including user and reference guides) are available at: [https://joular.github.io/joularjx/](https://joular.github.io/joularjx/).\r\n\r\n## :rocket: Features\r\n\r\n- Monitor power consumption of each method at runtime\r\n- Uses a Java agent, no source code instrumentation needed\r\n- Uses Intel RAPL (powercap interface) for getting accurate power reading on GNU/Linux, our research-based regression models on Raspberry Pi devices, and a custom program monitor (using a RAPL driver) for accurate power readings on Windows\r\n- Monitor energy of Java applications running in virtual machines\r\n- Provides real-time power consumption of every method in the monitored program\r\n- Provides total energy for every method on program exit\r\n\r\n## :package: Compilation and Installation\r\n\r\nTo build JoularJX, you need Java 11+ and Maven, then just build:\r\n\r\n```\r\nmvn clean install -DskipTests\r\n```\r\n\r\nAlternatively, you can use the Maven wrapper shipped with the project with the command:\r\n\r\n```\r\nLinux: ./mvnw clean install -DskipTests\r\nWindows: ./mvnw.cmd clean install -DskipTests\r\n```\r\n\r\nJoularJX depend on the following software or packages in order to get power reading:\r\n- On Windows, to read the data from the RAPL driver, we use a custom program monitor called [Power Monitor for Windows](https://github.com/joular/WinPowerMonitor). It used to be part of JoularJX, but now it is in its own repository. Download the binary (or compile the source code), and specify its path in ```config.properties```. Runs on Intel or AMD CPUs (since Ryzen).\r\n- On PC/server GNU/Linux, JoularJX uses Intel RAPL interface through powercap, and therefore requires running on an Intel CPU or an AMD CPU (since Ryzen).\r\n- On macOS, JoularJX uses `powermetrics`, a tool bundled with macOS which requires running with `sudo` access. It is recommended to authorize the current users to run `/usr/bin/powermetrics` without requiring a password by making the proper modification to the `sudoers` file.\r\n- On Raspberry Pi devices on GNU/Linux, JoularJX uses our own research-based regression models to estimate CPU power consumption with support for the following device models (we support all revisions of each model lineup. However, the model is generated and trained on a specific revision, listed between brackets, and the accuracy is best on this particular revision):\r\n  - Model Zero W (rev 1.1), for 32-bit OS\r\n  - Model 1 B (rev 2), for 32-bit OS\r\n  - Model 1 B+ (rev 1.2), for 32-bit OS\r\n  - Model 2 B (rev 1.1), for 32-bit OS\r\n  - Model 3 B (rev 1.2), for 32-bit OS\r\n  - Model 3 B+ (rev 1.3), for 32-bit OS\r\n  - Model 4 B (rev 1.1, and rev 1.2), for both 32 bits and 64-bit OS\r\n  - Model 400 (rev 1.0), for 64-bit OS\r\n  - Model 5 B (rev 1.0), for 64-bit OS\r\n- On virtual machines, JoularJX reads the power consumption of the virtual machine (measured in the host) from a file shared between the host and the guest.\r\n\r\nWe also support Asus Tinker Board (S).\r\n\r\n## :bulb: Usage\r\n\r\nJoularJX is a Java agent where you can simply hook it to the Java Virtual Machine when starting your Java program's main class:\r\n\r\n```\r\njava -javaagent:joularjx-$version.jar YourProgramMainClass\r\n```\r\n\r\nIf your program is a JAR file, then just run it as usual while adding JoularJX:\r\n\r\n```\r\njava -javaagent:joularjx-$version.jar -jar yourProgram.jar\r\n```\r\n\r\nJoularJX will generate multiple CSV files according to the configuration settings (in ```config.properties```), and will create these files in a ```joularjx-results```folder.\r\n\r\nThe generated files are available under the following folder structure:\r\n- joularjx-results\r\n  - appName-PID-start_timestamp\r\n    - all (power/energy data for all methods, including the JDK ones)\r\n      - runtime (power consumption every second)\r\n        - calltree (consumption for each call tree branch)\r\n        - methods (consumption for each methods)\r\n      - total (total energy consumption, generated at the program's end)\r\n        - calltree\r\n        - methods\r\n      - evolution (power consumption evolution of every method, throughout the execution of the application)\r\n    - app (power/energy data for methods of the monitored application, according to the ```filter-method-names``` setting)\r\n      - runtime\r\n        - calltree\r\n        - methods\r\n      - total\r\n        - calltree\r\n        - methods\r\n      - evolution\r\n\r\nJoularJX can be configured by modifying the ```config.properties``` files:\r\n- ```filter-method-names```: list of strings which will be used to filter the monitored methods (see Generated files below for explanations).\r\n- ```save-runtime-data```: write runtime methods power consumption in a CSV file.\r\n- ```overwrite-runtime-data```: overwrite runtime power data files, or if set to false, it will write new files for each monitoring cycle.\r\n- ```logger-level```: set the level of information (by logger) given by JoularJX in the terminal (allowed values: OFF, INFO, WARNING, SEVERE).\r\n- ```powermonitor-path```: Full path to the [Power Monitor for Windows](https://github.com/joular/WinPowerMonitor) program (only for Windows).\r\n- ```track-consumption-evolution```: generate CSV files for each method containing details of the method's consumption over the time. Each consumption value is mapped to an Unix timestamp.\r\n- ```hide-agent-consumption```: if set to true, the energy consumption of the agent threads will not be reported.\r\n- ```enable-call-trees-consumption```: compute methods call trees energy consumption. A CSV file will be generated at the end of the agent's execution, associating to each call tree it's total energy consumption.\r\n- ```save-call-trees-runtime-data```: write runtime call trees power consumption in a CSV file. For each monitoring cycle (1 second), a new CSV file will be generated, containing the runtime power consumption of the call trees. The generated files will include timestamps in their names.\r\n- ```overwrite-call-trees-runtime-data```: overwrite runtime call trees power data file, or if set to false, it will write new file for each monitoring cycle.\r\n- ```application-server```: properly handles application servers and frameworks (Sprig Boot, Tomcat, etc.). Set ```true``` when running on application servers. If false, the monitoring loop will check if the JVM is destroyed, hence closing JoularJX when the application ends (in regular Java application). If true, JoularJX will continue to monitor correctly as the JVM isn't destroyed in a application server.\r\n- ```vm-power-path```: the path for the power consumption of the virtual machine. Inside a virtual machine, indicate the file containing power consumption of the VM (which is usually a file in the host that is shared with the guest).\r\n- ```vm-power-format```: power format of the shared VM power file. We currently support two formats: ```watts``` (a file containing one float value which is the power consumption of the VM), and ```powerjoular``` (a csv file generated by [PowerJoular](https://github.com/joular/powerjoular) in the host, containing 3 columns: timestamp, CPU utilization of the VM and CPU power of the VM).\r\n\r\nYou can install the jar package (and the PowerMonitor.exe on Windows) wherever you want, and call it in the ```javaagent``` with the full path.\r\nHowever, ```config.properties``` must either be copied to the same folder as where you run the Java command or its location must be set with the ```-Djoularjx.config=/path/to/config.properties``` property when running your program.\r\n\r\nIn virtual machines, JoularJX requires two steps:\r\n- Installing a power monitoring tool in the host machine, which will monitor the virtual machine power consumption every second and writing it to a file (to be shared with the guest VM).\r\nFor example, you can use our [PowerJoular](https://github.com/joular/powerjoular).\r\n- Use JoularJ in the guest VM while specifying the path of the power file shared with the host and its format.\r\n\r\n## Generated files\r\n\r\nFor real-time power data or the total energy at the program exit, JoularJX generated two CSV files:\r\n\r\n- A file which contains power or energy data for all methods, which include the JDK's ones.\r\n- A *filtered file* which only includes the power or energy data of those filtered methods (can be configured in ```config.properties```). This data is not just a subset of the first data file, but rather a recalculation done by JoularJX to provide accurate data: methods that start with the filtered keyword, will be allocated the power or energy consumed by the JDK methods that it calls.\r\n\r\nFor example, if ```Package1.MethodA``` calls ```java.io.PrintStream.println``` to print some text to a terminal, then we calculate:\r\n\r\n- In the first file, the power or energy consumed by ```println``` separately from ```MethodA```. The latter power consumption won't include those consumed by ```println```.\r\n- In the second file, if we filter methods from ```Package1```, then the power consumption of ```println``` will be added to ```MethodA``` power consumption, and the file will only provide power or energy of ```Package1``` methods.\r\n\r\nWe manage to do this by analyzing the stacktrace of all running threads on runtime.\r\n\r\n## JoularJX Reader\r\n\r\nJoularJX Reader is a GUI to process, analyze and visualize JoularJX generated energy files.\r\nIt is available at its [own repository here](https://github.com/joular/joularjx-reader).\r\n\r\n## :bookmark_tabs: Cite this work\r\n\r\nTo cite our work in a research paper, please cite our paper in the 18th International Conference on Intelligent Environments (IE2022).\r\n\r\n- **PowerJoular and JoularJX: Multi-Platform Software Power Monitoring Tools**. Adel Noureddine. In the 18th International Conference on Intelligent Environments (IE2022). Biarritz, France, 2022.\r\n\r\n```\r\n@inproceedings{noureddine-ie-2022,\r\n  title = {PowerJoular and JoularJX: Multi-Platform Software Power Monitoring Tools},\r\n  author = {Noureddine, Adel},\r\n  booktitle = {18th International Conference on Intelligent Environments (IE2022)},\r\n  address = {Biarritz, France},\r\n  year = {2022},\r\n  month = {Jun},\r\n  keywords = {Power Monitoring; Measurement; Power Consumption; Energy Analysis}\r\n}\r\n```\r\n\r\n## :newspaper: License\r\n\r\nJoularJX is licensed under the GNU GPL 3 license only (GPL-3.0-only).\r\n\r\nCopyright (c) 2021-2024, Adel Noureddine, Université de Pau et des Pays de l'Adour.\r\nAll rights reserved. This program and the accompanying materials are made available under the terms of the GNU General Public License v3.0 only (GPL-3.0-only) which accompanies this distribution, and is available at: https://www.gnu.org/licenses/gpl-3.0.en.html\r\n\r\nAuthor : Adel Noureddine\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoular%2Fjoularjx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoular%2Fjoularjx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoular%2Fjoularjx/lists"}