PowerGoblin service
PowerGoblin Agent
1. Configuration file

Currently, no user-friendly graphical user interface is provided for configuration.

The PowerGoblin service can be configured in two ways: 1) command line parameters, and 2) global configuration file. There is an additional node configuration file for caching the state of the nodes.

PowerGoblin service

Global configuration file

On Linux, the global configuration has a well-defined XDG location, namely ~/.config/powergoblin/default.json. This file is basically a serialized version of the GlobalConfiguration structure defined in the source code file. The options are documented in the following tables:

Root level

Option	Default	Description
flags		Nested flags configuration, see flags
session		Nested session configuration, see session
plot		Nested plot configuration, see plot
name	"PowerGoblin instance"	Name of the PowerGoblin instance
statusPeriod	1000 (ms)	Timer period for status messages & device scan
logPath	"logs/"	Path to log files (relative to the application root)
httpContentPath	"web/"	Path to HTTP content (relative to the application root)
httpPort	8080	Port for HTTP access
telnetPort	9000	Port for telnet access
mqttHost	"localhost"	MQTT server host name
mqttPort	1883	Port for MQTT access
mqttTopicPrefix	auto-generated	Prefix for MQTT topics
simulatedCount	3	How many simulated meters to generate (with --simu). Simulated meters are only useful for demonstration purposes. The data is completely random. Note that simulated meters can also be added via the UI or API.

Flags

Option	Default	Description
modeDebug	False	Enable debug mode. By default only the most critical problems are displayed in the console. The debug mode produces more detailed output. It's still readable at real-time.
modeVerbose	False	Enable verbose debug mode. In this mode excessive amounts of debug data is generated to the console. It's a good idea to store this to a log file and analyse later.
modeInfo	False	Show only information about the meters, then quit. This is useful for quickly checking the state of the meters.
modeLowMemory	False	Enable the low-memory mode. Some memory intensive operations are disabled. The idea is that enough session data is collected so that the rest of the derived data can be built on a "larger" machine. If your sessions are not super long, this should not be needed.
modeInteractive	Auto	Interactive mode (exit with 'Enter'). Auto detected by default depending on the start up context. This option will not be read from the configuration file. In the headless mode (=false), no keyboard input will be monitored, and a kill signal needs to be sent to close the application.
modeStrictAPI	True	Prohibit RPC style calls via GET methods, warn about the use of local/latest entities
allowOriginHeader	False	Configures `'Access-Control-Allow-Origin: *'` header in web API requests, which makes it possible to submit resource data from Selenium JS sessions.
mqttClient	False	Enable MQTT client. MQTT is only used for broadcasting some high level events. Assumes that a MQTT server is available in the local network.
httpServer	True	Enable HTTP server. Without this option it's not possible to access the UI or control the instance.
telnetServer	False	Enable Telnet server. Telnet server is only needed for the telnet API. This server receives commands with lower overhead compared to the HTTP server.
logMeterEvents	True	Enable observers to log the events. This affects all meters in all sessions. When disabled, the readings will not produce session events. This is probably not something you want to disable.
deviceHotplug	True	Periodically scan for new devices. If this is disabled, meters cannot be added to the instance after the initialization. This might be good for debugging if your application crashes with this option enabled. Otherwise keep it enabled.
sessionLogs	True	Enable reading/writing of session logs. When disabled, no logs will be written to the disk, but live data can be seen in the UI. This is probably not something you want to disable if doing measurements.
nativeDrivers	True	Enable native drivers. When disabled, the physical meter devices will not be initialized. This might be good for debugging if your application crashes with this option enabled. RAPL/NVML still works. This is probably not something you want to disable.
ioUring	True	Enable the io_uring driver. When disabled, a generic socket handler is used for telnet.
implicitSession	False	Implicitly start a session with all the available meters. PowerGoblin 1.x did not have concurrent session support and the concept of session was implicit. This option is only useful for those old scripts. The new scripts require this to be disabled. If you enable this, e.g. the collectd http stream may trigger a concurrent session and redirect all the resource events to a wrong session.

Session

Option	Default	Description
name	"default"	Session name
author	"user"	Author name
description	"Generic measuring session"	Session description
resourceFilters	Memory, CPU load, disk, net, RAPL	List of collectd resource columns to include
scatterMaxDataPoints	2000	Maximum number of data points for scatter graphs
excludedRuns	[0]	Excluded runs from the summaries (assuming more than one run). Usually good to exlude run 0 as measurement initialization requires some time.
autoSave	True	Automatically save the session when closing. Otherwise and explicit store command is required.
writeDumps	True	Write the various data dumps in the log directory
writeReport	True	Write a report file when saving the session
writeLegacyReport	True	Write a legacy report file when saving the session
writeSpreadsheet	True	Write a spreadsheet file when saving the session
writePlotScripts	False	Write plot scripts when saving the session
writePlots	False	Write plots when saving the session

Plot

Option	Description
dockerImage	Docker image to use when generating plots
enableDocker	Use docker / native tools
renderingTimeOut	Generation timeout (rendering)

Meter configuration

When launching the application, for each detected SmartPower 3 meter, a configuration file such as powergoblin-SP3-3a08929c0deaea11a5a061e7994a5d01.json will be created on the launch directory. SP3 here refers to the type of meter and 3a08929c0deaea11a5a061e7994a5d01 to its serial number (either extracted from the meter's ROM or a virtual serial number generated from the device parameters).

The default configuration for the SP3 class of devices looks like this:

{
  "pollPeriod" : 10,
  "sampleRate" : 100,
  "portConfiguration" : {
    "baudRate" : "B115200",
    "dataBits" : "DataBits8",
    "stopBits" : "StopBits1",
    "parity" : "None",
    "flowControl" : "None"
  },
  "ignore" : false
}

The default configuration for the SP1 class of devices looks like this:

{
  "ignore" : false
}

The ignore field can be used to hide the meter. This is useful if some other instance of PowerGoblin is already using the meter.

The whole configuration will be rejected if any of the parameters is considered invalid. The data model of these configuration files may change so the files may need to be regenerated at some point.

Node configuration file

On Linux, the node configuration has a well-defined XDG location, namely ~/.config/powergoblin/nodes.json. This file is basically a serialized version of the node summary structures defined in the source code. Sometimes this file may need to be removed due to the propagation of erroneous data.

PowerGoblin Agent

Configuration file

Each launch of the agent updates the configuration file goblin-agent.json. The file is stored in the current working directory, and not in the standard XDG directory path. The purpose of this is to support multiple parallel instances of the agent on the same node.

The following listing demonstrates the default configuration stored in the configuration file after launching the agent for the first time in a clean system:

{
  "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 updated 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