From 1775edd8101bc43564a07e9f45de07cb0b8e3aaf Mon Sep 17 00:00:00 2001 From: Adel Noureddine Date: Tue, 2 Jul 2024 12:11:28 +0200 Subject: [PATCH] Update documentation with VM support for JoularJX --- src/joularjx/src/SUMMARY.md | 1 + src/joularjx/src/guide/supported_platforms.md | 4 ++- src/joularjx/src/overview.md | 1 + src/joularjx/src/ref/vm.md | 30 +++++++++++++++++++ .../src/guide/supported_platforms.md | 3 +- 5 files changed, 37 insertions(+), 2 deletions(-) create mode 100644 src/joularjx/src/ref/vm.md diff --git a/src/joularjx/src/SUMMARY.md b/src/joularjx/src/SUMMARY.md index 3f41e4e..ed7fcd1 100644 --- a/src/joularjx/src/SUMMARY.md +++ b/src/joularjx/src/SUMMARY.md @@ -13,4 +13,5 @@ - [Configuration Properties](./ref/configuration.md) - [Generated Files](./ref/generated_files.md) - [Integration with Systems and Tools](./ref/integration.md) +- [Virtual machines](./ref/vm.md) - [How JoularJX Works](./ref/how_it_works.md) \ No newline at end of file diff --git a/src/joularjx/src/guide/supported_platforms.md b/src/joularjx/src/guide/supported_platforms.md index 639e0ac..a7a3107 100644 --- a/src/joularjx/src/guide/supported_platforms.md +++ b/src/joularjx/src/guide/supported_platforms.md @@ -3,6 +3,7 @@ JoularJX support the following platforms and operating systems: - PC/Servers using a RAPL supported Intel processor (since Sandy Bridge) or a RAPL supported AMD processor (since Ryzen), on GNU/Linux, on Windows and on macOS. +- Virtual machines (any supported guest on any guest) The supported list of Raspberry Pi and Asus Tinker Board models are listed below. We support all revisions of each model lineup. @@ -26,4 +27,5 @@ However, the model is generated and trained on a specific revision (listed betwe | Windows PC/Server | Windows | Hubblo's Windows RAPL driver | x86, x86_64 | | macOS PC | macOS | Powermetrics | x86_64, ARM | | Raspberry Pi | GNU/Linux | Our regression models | ARM | -| Asus Tinker Board | GNU/Linux | Our regression models | ARM | \ No newline at end of file +| Asus Tinker Board | GNU/Linux | Our regression models | ARM | +| Virtual Machine | Supported guests (Windows, Linux, macOS), any host | Host's architecture (RAPL, regression models, others) | x86, x86_64, ARM | \ No newline at end of file diff --git a/src/joularjx/src/overview.md b/src/joularjx/src/overview.md index 62ecfbf..adf0ca2 100644 --- a/src/joularjx/src/overview.md +++ b/src/joularjx/src/overview.md @@ -20,6 +20,7 @@ The official website of JoularJX is: [https://www.noureddine.org/research/joular - Monitor power consumption of each method at runtime - Monitor the evolution of power consumption of each method - Monitor power consumption of methods' call tree and execution branches +- Monitor energy of Java applications running in virtual machines - Uses a Java agent, no source code instrumentation needed - 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 (based on Intel Power Gadget) for accurate power readings on Windows - Provides real-time power consumption of every method in the monitored program diff --git a/src/joularjx/src/ref/vm.md b/src/joularjx/src/ref/vm.md new file mode 100644 index 0000000..d4fb2ed --- /dev/null +++ b/src/joularjx/src/ref/vm.md @@ -0,0 +1,30 @@ +# Virtual Machines + +JoularJX also works inside virtual machines. +All its functionalities work the same inside a virtual machine as with bare metal installation. + +In virtual machines, JoularJX in the guest OS needs to get the power consumption of the virtual machine instance itself. +This can only be done by installing on the host OS, a power monitoring tool (such as PowerJoular or other ones), and monitoring the power consumption of the specific guest virtual machine process. + +The power data of the VM process need to be written to a shared file between the host and the guest. +Inside the guest, JoularJX will read this file continuously and use the reported power value as the power of the entire virtual machine. + +JoularJX is agnostic to what power tools in installed in the host and can work with any available tool that is capable of monitoring the VM process. + +## Use case example with JoularJX on guest and PowerJoular on host + +A use case example is using JoularJX on the guest OS and PowerJoular on the host OS. + +### In the host OS + +- Install [PowerJoular](https://github.com/joular/powerjoular) +- Run PowerJoular while specifying the PID of the virtual machine of the guest OS, and writing the power data in a CSV file in overwrite mode. +- For instance, you can run PowerJoular with the following command: ```powerjoular -p $VM_PID -o /home/vm/vm.csv``` +- Share the ```/home/vm/vm.csv``` between the host OS and the guest OS + +## In the guest OS + +- Get and compile JoularJX +- Share the ```/home/vm/vm.csv``` between the host OS and the guest OS, potentially having a different path of the file inside the guest. For instance, ```/opt/vm/vm.csv``` +- Modify ```config.properties``` and set ``vm-power-path``` to the shared file ```/opt/vm/vm.csv```, and ```vm-power-format``` to the proper format (in this case to ```powerjoular```). +- Start your Java application with JoularJX agent as usual. \ No newline at end of file diff --git a/src/powerjoular/src/guide/supported_platforms.md b/src/powerjoular/src/guide/supported_platforms.md index 8ede293..7db9cb6 100644 --- a/src/powerjoular/src/guide/supported_platforms.md +++ b/src/powerjoular/src/guide/supported_platforms.md @@ -38,4 +38,5 @@ We currently support the following Raspberry Pi models and Asus Tinker Board mod |:--------------:|:---------------------:|:-----------------------------:|:-----------------------------:| | Raspberry Pi | GNU/Linux | Our regression models | ARM | | Asus Tinker Board | GNU/Linux | Our regression models | ARM | -| Linux PC/Server | GNU/Linux | RAPL (using powercap), Nvidia-smi | x86, x86_64 | \ No newline at end of file +| Linux PC/Server | GNU/Linux | RAPL (using powercap), Nvidia-smi | x86, x86_64 | +| Linux Virtual Machine | GNU/Linux guest, any host | Host's architecture (RAPL, regression models, others) | x86, x86_64, ARM | \ No newline at end of file