6.2.9 Reporting State Data

As long as Moab Workload Manager is configured with MWS as a Resource Manager (RM), plugins can report state information on jobs, nodes, storage, and virtual machines to Moab HPC Suite. This is done through Reports that are generated by the plugin and passed to the bundled RM services (6.6.1 Job RM Service and 6.6.3 Node RM Service). Each report is for a specific type of object: job, node, storage, or virtual machine. Each contains current state information on the specific attributes of the type it is for.

Note that storage is a sub-type of node, meaning that it is a specialized node.

Generating Reports

To generate a report, simply create a new instance of a report depending on the type of object to be reported:

Each report has a single required parameter for creating a new instance—the ID of the object that is being reported. Once the report instance has been created, any property can be modified as shown in the API documentation links in the table above. The following example shows the creation of a simple node report and modification of a few properties:

public void poll() {
	NodeReport node = new NodeReport("node1")
	node.timestamp = new Date()
	node.operatingSystem = "centos-6.6-stateless"
	… // Set other properties and persist the report
}

Master and Slave Reports

At times, you may want to report some additional attributes on objects only if the objects are being reported by other plugins. For example, you may want to report the power state of a VM, but sometimes the plugin reporting this data can receive data even after the VM has been destroyed. In this case, you can set the slaveReport field on any report to true, signifying that the report should only be used if another plugin is reporting on the same object (in other words, creating 'master' reports).

If all reports for an object are 'slave' reports, and no 'master' reports exist, then the object will not report to Moab Workload Manager.

Special Cases in Field Values

All complex types, such as Lists, Maps, and objects (not including Enumerated values such as NodeReportState and JobReportState) have default values set for them and are not required to be instantiated before use. For example, the metrics property of a node report can be modified as follows:

public void poll() {
	NodeReport node = new NodeReport("node1")
	// The following assignments are equivalent in their functionality
	node.features.add("FEAT1")
	node.features << "FEAT2"
	// The following assignments are equivalent in their functionality
	node.metrics.METRIC1 = 4d
	node.metrics["METRIC2"] = 125.5
	… // Set other properties and persist the report
}

For the resources and requirements (jobs only) properties, assignments can be made easily without checking for previously existing values or null objects. For example, resources can be added to the resources property simply by accessing it as a Map:

public void poll() {
	NodeReport node = new NodeReport("node1")
	node.resources.RES1.total = 10
	node.resources.RES1.available = 3
	node.resources["RES2"].total = 10
	node.resources["RES2"].available = 10
	… // Set other properties and persist the report
}

The job report's requirements property has some additional handling to allow it to be accessed as a single JobReportRequirement object, such as in the following example:

public void poll() {
	JobReport job = new JobReport("job.1")
	job.nodeCountMinimum = 4
	job.processorCountMinimum = 2
	job.requiredNodeFeatures << "FEAT1"
	job.preferredNodeFeatures << "FEAT2"
	… // Set other properties and persist the report
}

Although multiple requirements can be added to the requirements list to provide consistency with the MWS Job resource (see 4.9  Jobs), only the first requirement object's properties will be reported to Moab HPC Suite through the RM interface.

Persisting a Report

After a report has been generated and all desired fields have been updated, the report must be sent to one of the three bundled RM services for persisting. If this is not done, the report will be discarded and will not be considered when reporting state information to Moab HPC Suite. The RM services are shown below according to the object type that they handle:

Each service has two methods: save and update. The difference between these is that the save method first removes all previous reports from the plugin calling the method, and then persists the new reports, thereby only persisting the latest reports, while the update method does not remove any reports before persisting the new reports. Typically, the save method will be used while a plugin is being polled, while the update method will be used in incremental event based reporting. An example of using the save method is shown below:

INodeRMService nodeRMService

public void poll() {
	NodeReport node = new NodeReport("node1")
	// Change the state
	node.state = NodeReportState.BUSY
	// Persist
	nodeRMService.save([node])
}

Once this is done, the reports will be persisted to MongoDB and will be included in RM queries (see 6.3.2 Resource Manager Queries) from Moab Workload Manager or users.