(Quick Reference)

NodeUtilizationReport Plugin

The Node Utilization Report plugin creates a report called "node-utilization" and creates samples for this report from the Nodes REST API. This report may be used to track or graph historical data of node CPU utilization. In order for this plugin to operate correctly, the CPU utilization metric (cpuUtilization) must be reported for nodes by plugins (see Reporting State Date) or MWM Resource Managers.

Configuration

Poll Interval

The Poll Interval controls how often samples are created for the report. It is recommended that this be set to 60 seconds.

Configuration Parameters

ParameterConfig KeyRequiredTypeDefaultDescription
High Utilization ThresholdhighThresholdYesDouble75A percentage between 0-100 representing the "high" utilization threshold.
Low Utilization ThresholdlowThresholdYesDouble25A percentage between 0-100 representing the "low" utilization threshold.
Report Consolidation DurationreportConsolidationDurationYesInteger900The number of seconds between datapoint consolidations. See datapointDuration field of reports.
Report SizereportSizeYesInteger-The number of datapoints to keep at one time in the report. See reportSize field of reports.

In order for the report to be created correctly (see below), the plugin configuration must be set correctly when the plugin is started. If it is not, the plugin configuration must be modified and the recreate-report custom web service (see below) must be used.

Exposed Web Services

MethodSecuredParametersParameter TypesDescription
recreate-reportYesNone-Destroys (if it exists) and recreates the node-utilization report using the current plugin configuration.

This web service will destroy any associated samples and datapoints for the node-utilization report. Only use this call if the reports parameters must be changed and the historical data does not need to be preserved.

Initially Created Plugins

A plugin called "node-report" will be created automatically when this plugin type is loaded. The configuration values of this initial plugin may be changed by setting properties in the MWS configuration file. These properties are shown in the following table along with the plugin configuration parameter they set and default values. They are shown in precedence, meaning if multiple MWS configuration properties set a single plugin configuration parameter, the property listed first in the table will be used if present, otherwise later properties will be used.

MWS Config PropertyPlugin Config ParameterDefault Value
plugins.reports.nodeUtilization.highThresholdhighThresholdPlugin Default
plugins.reports.nodeUtilization.lowThresholdlowThresholdPlugin Default
plugins.reports.nodeUtilization.reportConsolidationDurationreportConsolidationDurationPlugin Default
plugins.reports.defaults.reportConsolidationDurationreportConsolidationDurationPlugin Default
plugins.reports.nodeUtilization.reportSizereportSize10080 (1 week in seconds)
plugins.reports.defaults.reportSizereportSize10080 (1 week in seconds)

These values must be set before the plugin type is loaded for the first time. If the values were not set correctly, the plugin's configuration may be modified and the recreate-report web service may be called so that the report is created with the proper values.

Report

The first time the plugin is started, a report called "node-utilization" will be created using the plugin's configuration parameters. Each polling iteration then performs the following functions:

  1. Verify that the "node-utilization" report exists
  2. Query MWS Nodes API version 2 for the metrics.cpuUtilization field
  3. Each node is categorized according to its metric value:
    • If the metric value is null or missing, the node is marked as "unknown"
    • If the metric value is less than (not equal to) the low threshold, the node is marked "low"
    • If the metric value is greater than (not equal to) the high threshold, the node is marked "high"
    • Otherwise, the node is marked "medium"
  1. The total number of nodes is calculated
  2. The average of all metric values is calculated for all nodes that are not missing the cpuUtilization metric
  3. A sample for the "node-utilization" report is created with the data generated from the previous steps

As described in the Reporting Framework section of the guide, the samples are consolidated at a regular interval into datapoints, which can then be queried using the Get Datapoints For Single Report resource.

It is important to note that once the report is created on the first polling interval, the report will not be destroyed or recreated until the recreate-report custom web service is called.

Example

For the node query /rest/nodes?api-version=2&fields=metrics.cpuUtilization, suppose that the output looked like the following:

{
  "resultCount":10,
  "totalCount":10,
  "results":[
    {"metrics":{"cpuUtilization":0}},
    {"metrics":{"cpuUtilization":10}},
    {"metrics":{"cpuUtilization":25}},
    {"metrics":{"cpuUtilization":50}},
    {"metrics":{"cpuUtilization":75}},
    {"metrics":{"cpuUtilization":80}},
    {"metrics":{"cpuUtilization":100}},
    {"metrics":{}},
    {"metrics":{}},
    {"metrics":{"cpuUtilization":null}},
  ]
}

The resulting sample created would contain data that looked like the following:

{
  "high": 2,
  "low": 2,
  "medium": 3,
  "unknown": 3,
  "total": 10,
  "average": 48.571428571428571428571428571429
}