UTU Logo EU Logo ELY Logo EU Logo

  1. Starting the agent
  2. Configuration file
  3. Advanced use
    1. System service
  4. Next step: Setting up a measurement plan

This section shows how to start and use the PowerGoblin agent. The agent is a lightweight Java client that connects to the PowerGoblin service. The purpose of the agent is to manage the execution of measurements on the nodes. The agent can also perform preparatory tasks such as enumeration of measurement plans and calibration of the meters.

Starting the agent

This version of PowerGoblin agent requires OpenJDK 25 or later to run. We have instructions for installing Java here.

If you downloaded the jar distribution, it is recommended to do an initial setup by starting the agent with the intended name of the node and the address of the PowerGoblin instance:

$ java -jar powergoblin-agent.jar sut http://controller.lan:8080

This will set up the agent with the name sut and configures it to connect to the PowerGoblin instance at http://controller.lan:8080.

The agent configuration is stored in the current working directory. Later launches use the stored configuration:

$ java -jar powergoblin-agent.jar

That's it. The agent is usually run as a "passive" background process. All the coordination of measurement tasks is performed by the PowerGoblin service instance.

For example, you can start the agent inside a GNU screen / tmux session (first start screen, then start the agent, then detach with Ctrl-a + d). This naturally assumes that screen or tmux has been installed on the system. You can also set up a systemd service to run the agent. If you don't have any examples to run, the PowerGoblin web UI has a default functionality for downloading an example plan from the UTU servers. This works on any system with RAPL support and can be used for demonstrating the use of the application.

You can quite freely use the same node name on different machines and even have multiple working directories with different configurations. Just make sure that two agents do not simultaneously use the same node name. If this happens, different nodes will fetch commands from the same queue and output conflicting node data, which can lead to all kinds of incomprehensible problems.

Configuration file

Each launch of the agent updates the configuration file goblin-agent.json. The file is stored in the current working directory. This is an example of its contents after launching the agent with the command presented above:

{
  "name" : "sut",
  "description" : "generic node",
  "calibrationUnits" : {
    "CPULoad" : "cpu",
    "NetworkLoad" : "network",
    "DiskLoad" : "disk"
  },
  "rootPath" : ".",
  "server" : "http://controller.lan:8080",
  "collectdBinary" : "/usr/sbin/collectd",
  "powerOffArgs" : [ "/usr/bin/sudo", "/usr/sbin/systemctl", "poweroff" ],
  "rebootArgs" : [ "/usr/bin/sudo", "/usr/sbin/systemctl", "reboot" ],
  "defaultMeasurementDescription" : "measurement.md",
  "image" : "node.avif",
  "includeEnvironment" : false,
  "sleepDuration" : 1000,
  "reconfigureDuration" : 15000,
  "connectionTimeout" : 30,
  "debugConnection" : false
}

Only the server and name fields are update with new data when starting the agent with the two parameters. Other settings need to be manually configured.

The fields have the following meanings:

Field Default value Description
name sut Name of the node. Used as a target when enqueuing tasks
description generic node Short description of the node
calibrationUnits < see above > during the calibration task, attempts to map a meter to these units
rootPath . root path for locating measurement plans
server http://localhost:8080 URL of the PowerGoblin server
collectdBinary /usr/sbin/collectd path of the collectd binary
powerOffArgs /usr/bin/sudo /usr/sbin/systemctl poweroff command to run to power off the node
rebootArgs /usr/bin/sudo /usr/sbin/systemctl reboot command to run to reboot the node
defaultMeasurementDescription rootPath/*/measurement.md measurement plan description file
image node.avif image file that represents the node. This file is base64 encoded in the measurement report. A rather small avif file is recommended. Other formats are also supported.
includeEnvironment false collect the environment variables and include in the measurement report
sleepDuration 1000 ms polling period in the main loop, default:
reconfigureDuration 15000 ms period for reconfiguration (reads the measurement plans), default:
connectionTimeout 30 sec timeout for HTTP requests, default:
debugConnection false debug mode, displays more verbose output

Advanced use

System service

PowerGoblin agent can also be started as a background system service. This can be a particularly good solution because the agent is typically always used as a headless service. As a bonus, system services can hook up to the system logs.

Although the PowerGoblin agent may get stuck, especially if a measurement was misconfigured to use a huge timeout, the child processes simply refuse to shut down, we are quite confident that the agent can run as a background service. Of course, it should be noted that to ensure maximum reliability, it is advisable to verify the logs either from the web UI or the system logs.

PowerGoblin comes with a systemd service file that allows you to start the service in the background when the machine boots up:

[Unit]
Description=PowerGoblin Agent service
After=local-fs.target network.target

[Service]
SuccessExitStatus=143

[Service]
User=powergoblin
Type=simple
WorkingDirectory=/opt/powergoblin
ExecStart=/usr/bin/java -jar /opt/powergoblin/powergoblin-agent.jar sut http://controller.lan:8080
ExecStop=/bin/kill -15 $MAINPID
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Please note that you need a user called powergoblin for the service, which must be given the correct permissions (see #1 and #2). In addition, OpenJDK 25+ is required.

The following commands set up the user and the service binary on a system which already has OpenJDK configured:

$ sudo mkdir -p /opt/powergoblin
$ wget tech.utugit.fi/soft/visiiri/powergoblin/powergoblin-agent.jar
$ sudo mv powergoblin-agent.jar /opt/powergoblin
$ sudo chown -R powergoblin /opt/powergoblin

You can now enable the service as follows:

$ wget tech.utugit.fi/soft/visiiri/powergoblin/powergoblin-agent.service
$ sudo mv powergoblin-agent.service /etc/systemd/system/
$ sudo systemctl daemon-reload
$ sudo systemctl enable --now powergoblin-agent

Alternatively, you can also set up the unprivileged service for the current user:

[Unit]
Description=PowerGoblin Agent service

[Service]
SuccessExitStatus=143

[Service]
Type=simple
WorkingDirectory=/home/%u/pg
ExecStart=/usr/bin/java -jar /home/%u/pg/powergoblin-agent.jar sut http://controller.lan:8080
ExecStop=/bin/kill -15 $MAINPID
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

You can now enable the user service as follows:

$ mkdir -p .config/systemd/user pg
$ wget tech.utugit.fi/soft/visiiri/powergoblin/powergoblin-agent.jar -O pg/powergoblin-agent.jar
$ wget tech.utugit.fi/soft/visiiri/powergoblin/powergoblin-agent2.service -O .config/systemd/user/powergoblin-agent.service
$ systemctl --user enable --now powergoblin-agent
$ sudo loginctl enable-linger $USER

You can check that the agent works by visiting the web UI (http://controller.lan:8080).

In case the service gets stuck, you can run

$ sudo systemctl restart powergoblin-agent
$ sudo killall collectd -9
$ sudo killall collectd -15

or

$ systemctl --user restart powergoblin-agent

Please note that the service is not safe to run in a public network. We have not implemented any kind of security mechanisms.

Next step: Setting up a measurement plan

Please continue to the next phase for further instructions on setting up a measurement plan to be executed by the agent.

The API for controlling the agent is described here as well.