Skip to content

Commit

Permalink
docs: improve README to account for power-server use
Browse files Browse the repository at this point in the history
  • Loading branch information
metacosm committed Mar 29, 2024
1 parent 4bee46e commit 38fd183
Showing 1 changed file with 15 additions and 27 deletions.
42 changes: 15 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,48 +5,36 @@
This extension is an experiment to measure and display the power consumption of your application as it runs in Dev mode.
Only Linux/amd64 and macOS (amd64/apple silicon) are supported at the moment. See below for platform-specific
requirements.

## Requirements

### macOS

The power monitoring is performed using the bundled `powermetrics` tool, which requires `sudo` access. For convenience
and security, it's recommended you add your user to the `sudoers` file, giving it passwordless access
to `/usr/bin/powermetrics` (and possibly, only that).

### Linux

The extension makes use of the RAPL information accessible under the `/sys/class/powercap/intel-rapl` directory. For
security purposes, some of that information is only readable by root, in particular the values that we need to get the
power consumption, currently:
## Requirements

- /sys/class/powercap/intel-rapl/intel-rapl:1/energy_uj (if available)
- /sys/class/powercap/intel-rapl/intel-rapl:0/energy_uj
- /sys/class/powercap/intel-rapl/intel-rapl:0/intel-rapl:0:2/energy_uj
### power-server

For the extension to work properly, these files need to be readable by the current user, which you can accomplish by
running the provided `make_power_readable.sh` script. Note that this change will only persist until the next restart.
This extension relies on retrieving power consumption measurements from an application
called [power-server](https://github.com/metacosm/power-server). This application needs to be run using `sudo` to get
access to the underlying OS' power reporting layer. Please download the appropriate version for your OS from
the [release page](https://github.com/metacosm/power-server/releases/). Once downloaded, you can unpack
the archive and navigate to the `bin` directory to find the `power-server` binary that you can then run
using: `sudo power-server`.

## Usage

To use the extension:

1. Clone this repository locally
2. Build the code using `mvn install`
3. Add the extension to the application which energy consumption you wish to measure. Since the extension is not yet
released, you will need to add it manually as a dependency to your application:
1. Add the extension to the application which energy consumption you wish to measure. You can add it as a dependency to
your application:
```xml
<dependency>
<groupId>io.quarkiverse.power</groupId>
<artifactId>quarkus-power</artifactId>
<version>${project.version}</version>
</dependency>
```
4. Start your application in dev mode: `quarkus dev`
5. Enter the dev mode terminal by pressing `:` (column)
6. You should have a new `power` command available, type `power -h` for more information
7. You can start power measurement with `power start` and stop it with `power stop`, at which time the power consumption
2. Start your application in dev mode: `quarkus dev`
3. Enter the dev mode terminal by pressing `:` (column)
4. You should have a new `power` command available, type `power -h` for more information
5. You can start power measurement with `power start` and stop it with `power stop`, at which time the power consumption
of your app will be displayed.
8. You can also ask for power to be measured for a given duration by using the `-s` option when
6. You can also ask for power to be measured for a given duration by using the `-s` option when
calling `power start`. In this case, there's no need to call `power stop`, the energy consumed during the specified
time will be automatically displayed once the time period is elapsed.

0 comments on commit 38fd183

Please sign in to comment.