1. Java
2. RAPL
3. Limitations
4. RAPL permissions
   1. User configuration
   2. Udev rules
5. Set up MQTT (optional)
6. Set up HTTP (optional)
7. R and ggplot2 (optional)
8. Tips for low memory hardware
   1. Operating system level
   2. Application level
   3. PowerGoblin configuration
9. Next step: Launching the software

Java

PowerGoblin requires OpenJDK 25 or later to run. A Docker based installation is prepared to contain OpenJDK inside the Docker image. In other cases OpenJDK is required. For Windows and Mac, the easiest way is to install Eclipse Temurin. Linux distributions usually provide their own packages.

$ sudo apk add openjdk25-jre

$ sudo pacman -S jdk-openjdk

$ sudo apt install openjdk-25-jre

RAPL

Read this, if you don't (yet) have any external power meters or also want to measure using the internal meters (core, uncore, package, and/or the memory units) already available on your systems.

Machines with the RAPL (Running Average Power Limit) feature provide internal support for power / energy measurement. From the hardware perspective, supported CPU generations are:

Limitations

OS support: PowerGoblin only supports RAPL feature on Linux.

AMD: The RAPL on AMD platforms does not currently support the measurement of memory's energy consumption.

Apple: The Intel based Apple systems starting with 2nd gen Core also support RAPL. The more recent ARM based Apple machines use a distinct system that can be read with a 'powermetrics' utility, but is not currently supported.

RAPL permissions

PowerGoblin supports the reading of RAPL data on Linux. Not being able to read the RAPL counters from /sys/devices/virtual/powercap/intel-rapl as a non-root user is a common problem because the files in sysfs are typically owned by root with restrictive permissions. Running the entire application as root is not recommended.

A simple way is to change the ownership of the files:

$ sudo chown -R $USER /sys/devices/virtual/powercap/intel-rapl

This is not the most suitable way in multi-user systems and needs to be executed after each reboot. A better approach is to create a new group for users with access to the RAPL counters.

User configuration

The following commands will create a new group for RAPL access and add the user to the group:

sudo groupadd energy
sudo usermod -aG energy $USER

The group membership becomes active after relogin. Sometimes it might be easier to just reboot the system.

Udev rules

Now, create a new udev rule for RAPL access (in /etc/udev/rules.d/60-intel-rapl.rules):

SUBSYSTEM=="powercap", KERNEL=="intel-rapl*", \
    RUN+="/usr/bin/chgrp energy /sys/%p/energy_uj'", \
    RUN+="/usr/bin/chmod g+r /sys/%p/energy_uj"

Next, reload the new udev rules:

$ sudo udevadm control -R
$ sudo udevadm trigger

If this does not work, try rebooting the system.

Set up MQTT (optional)

This is not a mandatory step if you do not wish to use MQTT. MQTT is not the most suitable protocol for controlling the measurements because there is a noticeable latency when delivering messages. PowerGoblin mainly offers MQTT support only for broadcasting the high level measurement events. For controlling measurements, PowerGoblin uses HTTP or Telnet instead.

If you want to use the MQTT protocol, you will need to set up a separate MQTT server (PowerGoblin only works as a client), and some additional clients that are supposed to receive the messages. First, install the mosquitto package which contains all the client and server components:

$ sudo apk add mosquitto mosquitto-clients
$ sudo rc-update add mosquitto

$ sudo pacman -S mosquitto
$ sudo systemctl enable mosquitto

$ sudo apt install mosquitto mosquitto-clients
$ sudo systemctl enable mosquitto

If you use some other distribution, the package naming may differ. Debian based distributions also automatically enable new services. If the distribution offers both HTTP and HTTPS versions of MQTT, keep in mind that HTTPS is not currently supported by PowerGoblin.

You can test that the MQTT server is properly set up by launching the pub (publish) and sub (subscribe) applications:

$ mosquitto_sub -h localhost -t /test
$ mosquitto_pub -h localhost -t /test -m "Testing 123"

The mosquitto_sub client should receive the message.

Set up HTTP (optional)

PowerGoblin comes with an integrated lightweight HTTP server. This server is really lightweight - it does not contain any HTTPS support. If you need HTTPS, consider tunneling the traffic via a reverse proxy (lighttpd, nginx).

TODO: image of the setup

For the client side (SUT, system under test), you will need an HTTP client. Our examples either use the PowerGoblin client-side agent or scripts. Python / JavaScript / Java libraries or for shell scripts the curl and wget utilities. Both are available on most Linux distributions. The following commands will install curl and wget:

$ sudo apk add curl wget

$ sudo pacman -S curl wget

$ sudo apt install curl wget

The PowerGoblin's web UI not only communicates via HTTP, but contains a console for performing arbitrary HTTP queries.

R and ggplot2 (optional)

By default, PowerGoblin doesn't generate diagrams with R anymore, but if you want to use R, the following additional packages are also required for R/ggplot2 graph generation:

$ sudo apk add r

$ sudo pacman -S r

$ sudo apt install r-base r-cran-ggplot2 r-cran-stringr

Make sure ggplot2 and anytime packages are installed by invoking the following commands:

$ R
R version 4.4.1 (2024-06-14) -- "Race for Your Life"
Copyright (C) 2024 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu

> install.packages("ggplot2")
> install.packages("anytime")

It is also possible to run PowerGoblin without the need to install R and ggplot2, but graphs will not be generated for the measurements. The functionality will silently fail whenever there is a configuration issue with R.

If you forget to install the R packages, PowerGoblin will attempt to install them during the rendering process. Since there is a timeout set for the process, installation most likely will fail since the compilation usually takes much longer. The best way to avoid this issue is to prepare the R installation before doing any measurements.

Tips for low memory hardware

If less than optimal performance is acceptable, we have few recommendations:

Operating system level

Swap: We recommend either setting up a swap file in ZRAM (compressed ram disk) or a physical swap partition. A swap partition is often more efficient than a swap file. ZRAM should work especially well because the measurement data has lots of redundancy.

Disable background processes: For example, the suggested Diet Pi distribution for Raspberry Pi is configured to only start a very minimal set of background processes. Turning off processes (check systemctl and htop) and kernel drivers (check lsmod) can have a small or significant effect on the amount of free RAM.

Disable hardware features: Turning of hardware features such as GPU can have a significant effect, especially on lower-end hardware such as Raspberry Pi. Even on modern desktop class computers, a headless system usually has a lot more RAM free. The features must be disabled at boot time by editing the boot configuration scripts.

Disable transparent huge page support in the kernel: THPs can reserve a lot more RAM than 4k pages.

Application level

Lightweight apps: Optimizing the shell and other apps might use a bit less RAM, but not much.

PowerGoblin configuration

Fewer meters / channels / samples: collecting less data generates more data structures in memory. The application already streams the events to disk, but on very low-end systems this might help. A 200+ Hz sample rate might be useful for short sessions, but multiple meters and channels can produce gigabytes of data during a long session.

Resource filters: having stricter filters means less data will be collected. Especially for longer session, it is recommended to exclude all resources that are not relevant for the final report.

Disable services / features: turning off services / features also starts fewer background processes and accumulates less data. The telnet and mqtt features are not necessary. The OpenDocument spreadsheet, plot, and energy report generation are optional.

Enable the low-memory mode: The low-memory mode has a predefined set of rules for disabling some features that are not strictly needed for performing the measurement.

Native build: A native Graal build of the application could use less memory. This also requires switching to another JSON library (kotlinx-serialization). This is currently WIP. A native version will appear later.

Compact object headers: Compact object headers can shrink object size to save memory. You can enable the feature with the JVM option -XX:+UseCompactObjectHeaders.

Next step: Launching the software

Finally, all the preparations and configuration is done at this point. We can now continue to the next section where we launch the software and monitor its operation via the web user interface.

On the other hand, if you wish to learn more about the configuration options for PowerGoblin, see this subsection instead.