POST /metrics_service/metrics/servers

Use this method to return a specific number of top metric values among all or specific managed servers.

Note:
  • Depending on your environment and the number of managed hardware resources, it might take several minutes to retrieve the requested metrics data.

  • This REST API requires Lenovo XClarity Administrator v3.4.0 or later.

Authentication

Authentication with user name and password is required.

Request URL

POST https://{management_server_IP}/metrics_service/metrics/servers

Query parameters

You must specify either function, top, or bottom query parameters.

Parameter Required / Optional Description
bottom={integer} Required if function and top are not specified Returns a certain number of bottom (lowest) metric values among the specified devices during the entire period. This can be one of the following values.
  • 10. (default) Returns the 10 lowest values.

  • 50. Returns the 50 lowest values.

This is supported only when the metrics type is PowerInputWatts.

function={type} Required if bottom and top are not specified Aggregates data using the specified function. This can be one of the following values.
  • average. Statistical mean
  • max. Maximum
  • total. Total in the period with specified interval

    This is supported for only the PowerInputWatts metric type. The period and interval attributes must be specified.

interval={integer} Optional Returns metrics in the specified intervals, in seconds

The minimum interval is 30 seconds.

If the specified interval is greater than the specified period, the startTimestamp changes to the end timestamp minus the interval.

If not specified, the default interval is the sent by baseboard management controller for each measurement is used.

  • cpuTemp. 60 second intervals
  • averageCPUUtilization. 30 second intervals
  • averageMemoryUtilization. 30 second intervals
  • inletAirTemp. 60 second intervals
  • PowerInputWatts. 30 second intervals
  • PowerSupplyStats. 30 second intervals
metricsType={type} Optional Returns data only for the specified type. This can be one or more of the following values, separated by a comma.
  • cpuTemp. Average temperature for all processors, in Celsius
  • averageCPUUtilization. Average processor usage

  • averageMemoryUtilization. Average memory usage

  • inletAirTemp. Average temperature of the inlet air, in Celsius.
  • PowerInputWatts. Total power consumption for all power supplies, in Watts
  • PowerSupplyStats. Total power consumption for all power supplies, in Watts

If not specified, all metric types are returned.

period={integer} Required if bottom or top is specified Returns data that was collected in the specified amount of time, in minutes

You can specify from 1 – 1440 minutes. If not specified, 60 minutes of data is returned by default.

startTimestamp={timestamp} Optional Returns data that was collected starting at the specified time, using ISO-8601 format (for example, 2019-06-24T17:34:58+00:00)

If not specified, data is returned for the most recent period.

This date is specified using ISO-8601 format (for example, 2019-05-02). For information about ISO-8601 format, see the W3C Date and Time Formats webpage.

top={integer} Required if bottom and function are not specified Returns a certain number of top (highest) metric values among the specified devices during the entire period. This can be one of the following values.
  • 10. (default) Returns the 10 highest values.

  • 50. Returns the 50 highest values.

This is supported only when the metrics type is PowerInputWatts.

The following example returns the average averageMemoryUtilization and averageCPUUtilization metrics during a 30-minute period starting at the specified timestamp, in 30-second intervals.
POST https://192.0.2.0/metrics_service/metrics/servers
?metricsType=averageCPUUtilization,averageMemoryUtilization
&function=average&interval=30&startTimestamp=2021-07-27T04:09:17.802Z
The following example returns the maximum PowerInputWatts metrics during a 12-minute period starting at the specified timestamp in 1-minute intervals.
POST https://192.0.2.0/metrics_service/metrics/servers?metricsType=PowerInputWatts
&function=max&period=12&interval=1
The following example returns the top 10 average power-input metrics during the past 12 minutes, in 30-second intervals
POST https://192.0.2.0/metrics_service/metrics/servers?metricsType=PowerInputWatts
&top=10&period=12
The following example returns bottom 10 average power-input metrics during a 12-minute period starting at the specified timestamp, in 30-second intervals.
POST https://192.0.2.0/metrics_service/metrics/servers?metricsType=PowerInputWatts
&bottom=10&period=12

Request body

Attributes Required / Optional Type Description
uuids Required Array of strings Returns metrics data for one or more specific servers, specified by UUIDs separated by a comma

If not specified, statistics are returned all managed servers.

The following example returns metrics data for all managed servers.
{
   "uuids": []
}
The following example returns metrics data for specific managed servers.
{
   "uuids": ["65D5FDE03CC94343B772C881A06DDC96","E994C31710E03929884FBB1DBA8636EF"]
}

Response codes

Code Description Comments
200 OK The request completed successfully.
400 Bad Request A query parameter or request attribute is missing or not valid, or the operation is not supported. A descriptive error message is returned in the response body.
403 Forbidden The orchestrator server was prevented from fulfilling the request. A descriptive error message is returned in the response body. Ensure that you have privileges to perform the request.
409 Conflict There is a conflict with the current state of the resource. A descriptive error message is returned in the response body.
500 Internal Server Error An internal error occurred. A descriptive error message is returned in the response body.

Response body

The response varies based on the specified metric type.

Parameters Type Description
results Array of objects Information about metrics data that was collected for each server
  energyMetrics Object Information about energy metrics
    {metric_type} Array of objects List of data for the specified metric type. This can be one of the following types.
  • cpuTemp. Average temperature for all processors, in Celsius
  • averageCPUUtilization. Average processor usage

  • averageMemoryUtilization. Average memory usage

  • inletAirTemp. Average temperature of the inlet air, in Celsius.
  • PowerInputWatts. Total power consumption for all power supplies, in Watts
  • PowerSupplyStats. Total power consumption for all power supplies, in Watts
      index Integer Metric index, where 1 is the highest top value
      slot Integer Slot located, if applicable
      timestamp String Timestamp when the metric was collected, if applicable

This timestamp is specified using ISO-8601 format (for example, 2019-05-02T19:28:14.000Z). For information about ISO-8601 format, see the W3C Date and Time Formats webpage.

      uuid String UUID of the managed server
      value Integer Metric value
The following example is returned if the request is successful for the top 10 power-input metrics for three specific servers.
{
   "results": [{
      "energyMetrics": {
         "PowerInputWatts": [{
            "index": 1,
            "uuid": "6250520BB00EC21385165E09B719FB9E",
            "value": 103
         },
         {
            "index": 2,
            "uuid": "9B39E99CFE9A2D4F05F742B8838833A8",
            "value": 103
         },
         {
            "index": 3,
            "uuid": "4640A41E125FEC3FFFD48B7A2C98318E",
            "value": 102
         }]
      }
   }]
}
The following example is returned if the request is successful for the top 10 processor-temperature metrics for a specific server.
{
   "results": [{
      "energyMetrics": {
         "cpuTemp": [{
            "index": 1,
            "slot": 2,
            "timeStamp": "2021-11-30T09:04:54.652Z",
            "uuid": "4673074666D7082E090685B14CDDD245",
            "value": 50
         }
      ]}
   }]
}
The following example is returned if the request is successful for the top 10 inlet air-temperature metrics for a specific server.
{
   "results": [{
      "energyMetrics": {
         "inletAirTemp": [{
            "timeStamp": "2021-12-14T14:26:54.954Z",
            "uuid": "7167F89D7DB1F1659842B4460AD1BEAD",
            "value": 41
         },
         {
            "timeStamp": "2021-12-14T14:30:26.861Z",
            "uuid": "C3548BD5AF2C9ADD03485147EA2595C7",
            "value": 50
         }]
      }
   }]
}