UTU Logo EU Logo ELY Logo EU Logo

  1. Agent's operating modes
  2. Commands
    1. Calibrate
    2. Determine capabilities
    3. Execute
    4. Measure
    5. Reconfigure
    6. Collect
    7. Exit
    8. Poweroff
    9. Download

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 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

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, 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. The provided description is either the id (directory name) or the UUID of the measurement.

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

Example (perform the measurement in workDir/agent-collectd/measurement.md in normal mode):

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

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 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