PowerGoblin User Manual - PowerGoblin User Manual - Launching the PowerGoblin agent

Agent's operating modes
API endpoints
Commands

This section describes the use of the command API to control the PowerGoblin agents. The commands are first enqueued on the PowerGoblin instance. The instance stores the commands in a FIFO queue, and agents located on nodes can fetch the commands assigned to their id. The agents are typically controlled from the PowerGoblin web UI.

The agent is a lightweight Java client that connects to the PowerGoblin service. The current system has some downsides, but makes it easier to implement rather simple agent software in any language. The agents are also free to support only a subset of the functionality. A server mode for the agents might be implemented in the future.

Agent's operating modes

The agent first does a test run to see whether collectd is available and what features it can support. Then it starts a loop and automatically attempts to register the node. After registering, it polls for new tasks. If the connection is lost, it moves back to the registration phase.

Initialization / reconfiguration
- read the configuration
- discover the node specs
- read the node image
- parse the measurement plans
- discover the collector (collectd) capabilities
Task loop (not connected)
- reconfigure every 15 seconds (default)
- register the node
- if successful, go to the other loop
- otherwise, repeat until connected
Task loop (connected)
- reconfigure every 15 seconds (default)
- fetch the list of commands assigned to this node
- send an update message of the agent status
- execute the commands in order, if received any
- if disconnected, go to the other loop
- otherwise, repeat until connected

API endpoints

The agent command API is available via the following PowerGoblin service API endpoints:

Method	Endpoint	Description	Direction

POST	/api/v2/cmd	Execute `nodeClearLog`, `nodeRemove`. Payload: serialized Command object	UI -> Service
GET	/api/v2/node	Return the list of summaries of all nodes.	UI -> Service
POST	/api/v2/node	Register a node. Payload: serialized NodeSpecs object	Agent -> Service
GET	/api/v2/node/:node	Return the state of the node.	UI -> Service
POST	/api/v2/node/:node/collectd-stream	Sink for collectd resource streams (http plugin). Payload: resource stream	Agent -> Service
GET	/api/v2/node/:node/commands	Return the list of enqueued node commands.	Agent -> Service
POST	/api/v2/node/:node/enqueue	Enqueue an agent command. Payload: serialized AgentCommand object	UI / Agent -> Service
POST	/api/v2/node/:node/execute	Enqueue a agent execute command. Payload: space separated list of command line arguments	UI -> Service
POST	/api/v2/node/:node/message	Append a node message. Payload: message content	Agent -> Service
POST	/api/v2/node/:node/status	Update the agent status. Payload: serialized AgentStatus object	Agent -> Service
POST	/api/v2/null	Null sink for collectd calibration streams. Payload: stream	Agent -> Service

The typical workflow is UI/script → Service → Agent and Agent → Service. The agents also use the enqueue API for sending collection start/top commands to other nodes.

Commands

The PowerGoblin web UI provides a default set of functionality built on top of this command API. Please see the source code for more examples of using the API.

Calibrate

Performs a calibration. The purpose of the calibration is to generate artificial load (e.g. cpu, disk, network). This usually consumes more power than running the system idle. This can be used to determine the association between a meter/channel and a node/unit.

The tasks should have CPULoad / NetworkLoad / DiskLoad as first target. The second task should be Idle.

{
  "type": "calibrate",
  "targets": [
    "CPULoad", "Idle"
  ],
  "threshold": 50000.0,
  "delta" : 1.04,
  "timeOut": 4,
  "removeTask": true
}

Example (perform the calibration of the meter associated with cpu load, use default settings otherwise):

{
  "type": "calibrate",
  "targets": [
    "CPULoad", "Idle"
  ]
}

Determine capabilities

Determines the collectd capabilities. Usually run at startup.

{
  "type": "determineCapabilities",
  "targets": [
    "ACTIVE",
    "HTTP",
    "RAPL",
    "NVML"
  ],
  "timeOut": 2
}

Example (determine the capabilities of the collector, default: test all the functionality):

{
  "type": "determineCapabilities"
}

Execute

Executes a single command on the node. There is a timeout for all commands. The work directory can be defined or omitted (uses the current work directory). In debug mode the agent sends back command output after each line. Otherwise, the whole output is submitted after the execution is done.

{
  "type": "execute",
  "args": [
    "path to executable",
    "argument1",
    "argument2"
  ],
  "timeOut": 180,
  "workDirectory": "path",
  "debugMode": false,
  "startTask": true
}

Example (execute 'echo hello' on the node):

{
  "type": "execute",
  "args": [ "/bin/echo", "hello" ]
}

Measure

Performs a measurement on the node. This includes setting up the session, synchronizing the clocks, starting the collector(s), calling the scripts. The provided description is either the id (directory name) or the UUID of the measurement. The debug mode is a bit slower and produces more network traffic because all output as piped directly. If the remove flag is enabled, the session will be automatically removed (from memory) after closing.

{
  "type": "measure",
  "description": "id or uuid",
  "debugMode": false,
  "remove": false
}

The following example assumes that the project directory workDir/agent-collectd exists. Inside the directory the plan can be found in measurement.md. In addition, there is a unique id defined in _unique.id, namely 53a3d8d3-cf74-4785-91f6-bb2fd010cf68.

To start the measurement in non-debug mode, any of the following should work:

Using directory path:

{
  "type": "measure",
  "description": "agent-collectd"
}

Using direct file path:

{
  "type": "measure",
  "description": "agent-collectd/measurement.md"
}

Using unique id:

{
  "type": "measure",
  "description": "53a3d8d3-cf74-4785-91f6-bb2fd010cf68"
}

Reconfigure

Reconfigures the agent on the node. Can be configured to do a search for new measurements.

{
  "type": "reconfigure",
  "locateMeasurements": true,
  "explicit": true
}

Example (perform full reconfiguration):

{
  "type": "reconfigure"
}

Collect

Starts a collectd background collection task. The capabilities of the node have been discovered during the initialization. Only those features supported by the node will be enabled. The interval (decimal number, in seconds) is passed to collectd.

{
  "type": "collect",
  "flags": [
    "ACTIVE",
    "HTTP",
    "RAPL",
    "NVML"
  ],
  "session": "id of the session",
  "timeOut": 3600,
  "interval" : "0.1",
  "debugMode": false
}

{
  "type": "collectorStop"
}

Exit

Attempts to exist the node.

{
  "type": "exit"
}

Poweroff

Attempts to power off or reboot the node.

The variant for powering off:

{
  "type": "poweroff",
  "reboot": false
}

The variant for rebooting:

{
  "type": "poweroff",
  "reboot": true
}

Download

Attempts to download a zip file and store it locally. A new target directory is generated. The provided UUID is stored in the file _unique.id in the target directory.

If the target already exists, a new name is generated. Example: "foobar" is defined as the target. The directories "foobar" and "foobar-1" already exist, but "foobar-2" does not exist. The directory "foobar-2" is created and selected.

{
  "type": "download",
  "source": "source http/https url of the zip file",
  "target": "target directory",
  "uniqueId": "UUID for the plan"
}

Example: the following example is also provided in the web UI

{
  "type": "download",
  "source": "https://ftdev.utu.fi/vm-data/test.zip",
  "target": "testproject"
}

The zip file is extracted to the directory testproject:

testproject/
testproject/config.png
testproject/measurement.md
testproject/start.sh
testproject/algorithm3.sh
testproject/algorithm2.sh
testproject/algorithm1.sh