From 76d7ebcf7b45123397f9e8f63f872d8a22fc5177 Mon Sep 17 00:00:00 2001 From: keilhofh <127299248+keilhofh@users.noreply.github.com> Date: Thu, 19 Oct 2023 08:15:19 +0200 Subject: [PATCH] release 1.0.2 --- CHANGELOG.md | 20 ++++--- README.md | 65 +++++++++++----------- src/main/resources/csvExport_es.properties | 13 +++++ version.txt | 2 +- 4 files changed, 59 insertions(+), 41 deletions(-) create mode 100644 src/main/resources/csvExport_es.properties diff --git a/CHANGELOG.md b/CHANGELOG.md index e083262..cae0f66 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,16 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [not yet released] -- remove TODO from artifactory.gradle -- some minor fixes: - - adding constants - - no infinite loop on misconfigured csv delimiter, +- currently nothing here + +## 2023-10-19 - release 1.0.2 +- replace discontinued Open Hardware Monitor by fork Libre Hardware Monitor +- add spanish resource bundle for csv export + +## 2023-10-18 - release 1.0.1 +- some minor fixes: + - adding constants + - no infinite loop on misconfigured csv delimiter, - fix NaN on first measurements with zero duration. +- remove TODO from artifactory.gradle - upgrade dependencies -- replace discontinued Open Hardware Monitor by fork Libre Hardware Monitor -## 2023-03-07 -- refactoring and release 1.0.0 +## 2023-03-07 - release 1.0.0 +- refactoring - upgrade to gradle 8 ## 2022-05-31 diff --git a/README.md b/README.md index 8c12f4b..ae9c1f0 100644 --- a/README.md +++ b/README.md @@ -8,28 +8,24 @@ The Java agent collects the activity of the application to be measured at regula The CPU usage of the program and the current power consumption are aggregated to energy consumption per method over runtime and written into a CSV file. The result of the measurement is the energy consumption in watt hours or joule. -### Prerequisites -- Tool Libre Hardware Monitor is installed: https://github.com/LibreHardwareMonitor/LibreHardwareMonitor -- Libre Hardware Monitor is configured to start a web server: - ![Webserver aktivieren](docs/lhm-webserver.png) -- If necessary, an alternative port (default is 8085) can be also activated there. -- __IMPORTANT: To start the web server, Libre Hardware Monitor may have to be started as administrator.__ -- After that the tool is also accessible in the browser: http://localhost:8085/. -- The JUnit extension internally reads the json document, which can be retrieved at http://localhost:8085/data.json. -- __To start the Java agent, the "fat jar" (incl. dependencies) first must be built using the Gradle task "shadowJar"__. -- __Copy "src/main/resources/jpowermonitor-template.yaml" to the execution directory and rename to "./jpowermonitor.yaml"__. -- __Configure (at least) measurement -> lhm -> paths -> path to fit your machine__. -- Tool HWiNFO could be used alternatively, __measurement -> method__ must be set to 'csv' and Logging to CSV in HWiNFO must be active: https://www.hwinfo.com/ - -### Java Agent -- For testing call with `java -javaagent:.\build\libs\jpowermonitor-1.0.2-SNAPSHOT-all.jar[=path-to-jpowermonitor.yaml] -jar .\build\libs\jpowermonitor-1.0.2-SNAPSHOT-all.jar [runtimeSeconds] [cpuThreads]` -- .\build\libs\jpowermonitor-1.0.2-SNAPSHOT-all.jar is just an example and can be replaced by any *.jar of your choice -- For starting the agent with Spring Boot, Servlet-Container etc. please consult the respective documentation for adding a java agent. - -### Limitations -- The tool currently only works with German locale setting. - -### Configuration +### Quick Start +- Install and configure Tool __Libre Hardware Monitor__: https://github.com/LibreHardwareMonitor/LibreHardwareMonitor + - Configure Libre Hardware Monitor to start a web server: + ![Webserver aktivieren](docs/lhm-webserver.png) + - If necessary, an alternative port (default port is 8085) can be also activated there. + - __IMPORTANT: To start the web server, Libre Hardware Monitor may have to be started as administrator.__ + - After that the tool is also accessible in your browser: http://localhost:8085/. + - The jPowerMonitor JUnit extension and the Java Agent internally read the json document, which can be retrieved at http://localhost:8085/data.json. +- The tool __HWiNFO__ or __another tool that writes sensor values to a CSV file__ could be used alternatively, __measurement -> method__ must be set to 'csv' and Logging to CSV in HWiNFO must be active: https://www.hwinfo.com/ + - Configure HWiNFO to log the values of the power sensors to the CSV file. + - Start the logging in HWiNFO to a file e.g. in your project directory. +- To start the __Java agent__, the "fat jar" (incl. dependencies, with name `jpowermonitor--all.jar`) must be __downloaded from mvn central [here](https://repo.maven.apache.org/maven2/io/github/msg-systems/jpowermonitor/)__ or __must first be built__ with the Gradle task `shadowJar`. +- __Copy `src/main/resources/jpowermonitor-template.yaml` to the execution directory and rename it to `./jpowermonitor.yaml`__. +- __Configure (at least) measurement -> lhm -> paths -> path to match your machine__ for using Libre Hardware Monitor, or __the CSV section__ to use HWiNFO or __another tool that writes sensor values to a CSV file__. +- For using the __JUnit Extension__ see below section __[JUnit Tests](#JunitTests)__ +- For more configuration settings see below section __[Configuration](#Configuration)__. + +### Configuration The configuration is done via a YAML file. Normally this would be `jpowermonitor.yaml`. The agent has multiple ways of getting this configuration: 1. You can pass it as a programm argument, see section above. If not, it will simply assume the name @@ -72,24 +68,24 @@ For the configuration of the JUnit extension a yaml file with the name of the ex If no base load (`energyInIdleMode`) is specified for a path, this is measured before each test. So a mixed operation between configuration of the base load and measurement is also possible and the results can be compared (some sensors provide very similar values). For non current measuring sensors (e.g. temperature) the base load is not calculated extra and also not subtracted from the measured value! It is only output if a base load must also be calculated for a current-measuring sensor because this is not specified in the configuration. -### Integration into own project -#### Gradle -You may build the jpowermonitor fat jar using the build target `shadowJar` and the copy the `-all.jar` into a folder of your project. +### Integration into your own project +#### Java Agent +- You may build the jpowermonitor fat jar using the build target `shadowJar` and the copy the `-all.jar` into a folder of your project. +- You can use this jar for the java agent. Alternatively you may download the fat jar from mvn central [here](https://repo.maven.apache.org/maven2/io/github/msg-systems/jpowermonitor/). +- For testing call with `java -javaagent:.\build\libs\jpowermonitor--all.jar[=path-to-jpowermonitor.yaml] -jar .\build\libs\jpowermonitor--all.jar [runtimeSeconds] [cpuThreads]` +- The second `.\build\libs\jpowermonitor--all.jar` is just an example and can be replaced by any `jar` of your choice +- The configuration can be passed as a parameter using the `=` sign! If nothing is passed, the default configuration file `jpowermonitor.yaml` is searched. +- For starting the agent with Spring Boot, Servlet-Container etc. please consult the respective documentation for adding a java agent. -The add the test dependency to your gradle build (analogue for maven builds): -``` - testImplementation files('libs/jpowermonitor-1.0.2-all.jar') -``` -Alternatively you call the build target `publishLocal` in the jPowerMonitor project and publish the jar to your local maven repository. -You then add the following test dependency to your build script: +#### JUnit Tests +The add the test dependency to your gradle build (analogue for maven builds): ``` testImplementation( - [group: 'group.msg', name: 'jpowermonitor', version: jPowerMonitorVersion], + [group: 'io.github.msg-systems', name: 'jpowermonitor', version: jPowerMonitorVersion], ) ``` -#### JUnit Tests The extension is designed for JUnit 5 (jupiter) tests and is included into your test class as follows: ``` @ExtendWith({JPowerMonitorExtension.class}) @@ -123,6 +119,9 @@ The headers of the csv output file are configured in the [csvExport.properties]( The file currently is translated into German and French and is locale dependent. You may add your own locale and add the translated file to the classpath. You may set the language via JVM option e.g. `-Duser.language=es`. +### Limitations +- There are currently no known limitations. + #### Note This markdown can be converted to html with `pandoc --self-contained -t slidy -c docs/slidy.css -o Readme.html README.md` to html and from there to pdf via print function of the browser. diff --git a/src/main/resources/csvExport_es.properties b/src/main/resources/csvExport_es.properties new file mode 100644 index 0000000..1af43e3 --- /dev/null +++ b/src/main/resources/csvExport_es.properties @@ -0,0 +1,13 @@ +measureTime=Hora +measureName=Nombre +sensorName=Sensor +sensorValue=Valor +sensorValueUnit=Unidad +baseLoad=Carga base +baseLoadUnit=Unidad +valuePlusBaseLoad=Valor+Carga base +valuePlusBaseLoadUnit=Unidad +energyOfValue=Energía(Valor) +energyOfValueUnit=Unidad +energyOfValuePlusBaseLoad=Energía(Valor+Carga base) +energyOfValuePlusBaseLoadUnit=Unidad diff --git a/version.txt b/version.txt index 276823b..6d7de6e 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -1.0.2-SNAPSHOT +1.0.2