Get Energy Optimization Advice Details

The Get Energy Optimization Advice Details operation returns detailed information about currently available energy optimization advice for a CPC. This operation is supported using the BCPii interface.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/get-energy-optimization-advice-details

In this request, the URI variable {cpc-id} is the object ID of the CPC whose energy optimization advice details are to be returned.

Request body contents

The request body is expected to contain a JSON object with the following fields:

Field name Type Rqd/ Opt Description
timescale String Enum Optional Timescale for the advice graph data points. This is the amount of time to be covered by the data points in the graph. Valid values are:
  • "four-hours"
  • "one-day"
  • "three-days"
  • "one-week"

If not specified, the default is "one-day".

type String Enum Required The type of advice details to return. Valid values are:
  • "environmental" - Advice about environmental aspects of energy management such as air temperature.
  • "processor-utilization" - Advice related to the processor utilization in the CPC.

Response body contents

On successful completion, the response body contains a JSON object that provides the values of the specific energy optimization advice object requested from the CPC. The advice object contains a set of fields common to all types of advice, and a set of additional fields that differ based on the advice type.

The common fields provided for all types of advice are defined in the following table:

Field name Type Description
type String Enum Identifies the advice type. Valid values are:
  • "environmental" - Advice about environmental aspects of energy management such as air temperature.
  • "processor-utilization" - Advice related to the processor utilization in the CPC.
timestamp Timestamp The time when this advice was created or updated. This field and the last-energy-advice-time property of the CPC are updated each time the status field is updated.
summary String (0-153) Human readable description of the status field.
status String Enum The current status of the parameters factored into this advice. The valid values for this field depend on the value of the type field.

When type is "environmental":

  • "optimal" - Parameters related to this advice are currently at optimal values; no changes are recommended at this time.
  • "above-threshold" - One or more of the parameters is above its threshold; changes are recommended.

When type is "processor-utilization":

  • "low-utilization" - System utilization is low. If static power save is enabled, power consumption can be reduced by the amount specified in the power-saving field.
  • "low-utilization-power-save" - System utilization is low, but static power save is enabled.
  • "high-utilization" - System utilization is high and the system is configured optimally.
  • "high-utilization-power-save" - System utilization is high, but static power save is enabled. Performance can be increased by disabling static power save on the system.

When the type field contains "environmental", the response body also contains the following additional type-specific fields:

Field name Type Description
ambient-temperature Float The ambient temperature when this advice was generated, in degrees Celsius.
wattage Integer The electrical power usage when this advice was generated, in Watts.
temperature-threshold Float The temperature threshold that causes an increase of the system power consumption, in degrees Celsius.
power-saving Integer The amount of electrical power that can be saved when following this advice, in Watts.
temperature-graph Array of float-data-point objects An ordered collection of temperature data points, in descending time order, beginning with the most recent, covering as much of the requested time period as is available. Each element of this array is a float-data-point object representing the ambient environment temperature in degrees Celsius at a specific point in time. The interval is implicit given by the timestamps of the individual data points.
wattage-graph Array of integer-data-point objects An ordered collection of electrical power data points, in descending time order, beginning with the most recent, covering as much of the requested time period as is available. Each element of this array is an integer-data-point object representing the total system power, in Watts, at a specific point in time. The interval is implicit, given by the timestamps of the individual data points.

When the type field contains "processor-utilization", the response body also contains the following additional type-specific fields:

Field name Type Description
wattage Integer The electrical power usage when this advice was generated, in Watts.
power-saving Integer The amount of electrical power that will be saved by following this advice, in Watts.
utilization-threshold Integer (0-100) The threshold in percentage. The threshold is used to calculate the current system status. If system utilization is below the threshold, enabling static power save should be considered.
utilization Array of type-utilization objects List of all processor types installed in the CPC and their percent utilization at the time this advice was created.
static-power-save-recommended Boolean Indicates whether enabling static power save is recommended. True if recommended; false otherwise.
utilization-graphs Array of type-utilization-graph objects A collection of processor utilization graphs. Each element of this array contains the utilization graph of a processor type available in the system.

Each nested float-data-point object contains the following fields:

Field name Type Description
data Float Floating point data value.
timestamp Timestamp The time when this data point was taken

Each nested integer-data-point object contains the following fields.

Field name Type Description
data Integer Integer data value.
timestamp Timestamp The time when this data point was taken.

Each type-utilization-graph object contains the following fields:

Field name Type Description
type String Enum The processor type. Valid values are:
  • "cp" - Central (general purpose) processor.
  • "icf" - Internal Coupling Facility processor.
  • "ifl" - Integrated Facility for Linux® processor.
  • "sap" - Service assist processor.
  • "sys" - Total system utilization. (Used for threshold monitoring).
utilization-graph Array of integer-data-point objects An ordered collection of utilization data points, in descending time order, beginning with the most recent, covering as much of the requested time period as is available. Each element of this array is an integer-data-point object representing the utilization of the processor type in percentage at a specific point in time. The interval is implicit, given by the timestamps of the individual data points.

Each nested type-utilization object contains the following fields:

Field name Type Description
type String Enum The processor type. Valid values are:
  • "cp" - Central (general purpose) processor.
  • "icf" - Internal Coupling Facility processor.
  • "ifl" - Integrated Facility for Linux processor.
  • "sap" - Service assist processor.
  • "sys" - Total system utilization. (Used for threshold monitoring).
utilization Integer (0-100) The current utilization in percentage for the given processor type.

Description

This operation returns detailed information about the requested type of energy optimization advice for the CPC object specified by {cpc-id}.

On successful execution, the energy optimization advice details for the requested type of advice for the CPC are provided in the response body, and HTTP status code 200 (OK) is returned. The details cover as much of the requested time period as is available.

If the request URI does not identify a CPC object to which the API user has object-access permission, HTTP status code 404 (Not Found) is returned.

Authorization requirements

This operation has the following authorization requirements:
  • For the web services interface:
    • Object-access permission to the CPC object identified in the request URI.
    • Action/task permission to the Energy Optimization Advisor task.
  • For the BCPii interface, the source partition must have receive BCPii security controls permissions for the CPC object.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in Response body contents.

Otherwise, the following HTTP status codes are returned for the indicated errors. The response body is a standard error response body providing the reason code indicated and associated error message.

Table 1. Get Energy Optimization Advice Details: HTTP status and reason codes
HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. SeeCommon request validation reason codes for a list of the possible reason codes.
403 (Forbidden) 0 The request used the BCPii interface and the source partition does not have receive BCPii security controls permission for the CPC object.
1 The user under which the API request was authenticated does not have the required authority to perform the requested action.
404 (Not Found) 1 The request URI does not designate an existing CPC, or it designates a CPC for which the API user does not have object-access permission.
4 The object designated by the request URI does not support the requested operation.
409 (Conflict) 329 The operation cannot be performed because the CPC designated by the request URI is an unmanaged CPC, which is not supported by this operation.
503 (Service Unavailable) 1 The request could not be processed because the HMC is not currently communicating with an SE needed to perform the requested operation.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. Get Energy Optimization Advice Details: Request
POST /api/cpcs/a44d8ab8-e68e-3a07-9bff-e484a62ca00d/operations/get-energy-optimization-
   advice-details HTTP/1.1
x-api-session: 2szwxczuje9cttj01145ozlab65x9osmpvvdibob5w0nvgwm80
content-type: application/json
content-length: 52
{
   "timescale":"four-hours",
   "type":"environmental"
}

Figure 2. Get Energy Optimization Advice Details: Response (Part 1)
200 OK
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Tue, 08 Mar 2016 19:32:27 GMT
content-type: application/json;charset=UTF-8
content-length: 2683
{
   "ambient-temperature":24.200000762939453,
   "power-saving":126,
   "status":"above-threshold",
   "summary":"The ambient temperature is above the current threshold of 23.0\u00b0C 
      (73.4\u00b0F). If the ambient temperature is lowered below the identified threshold, 
      the system power consumption will be reduced by approximately 126 W.",
   "temperature-graph":[
      {
         "data":23.80500030517578,
         "timestamp":1457451614605
      },
      {
         "data":23.577499389648438,
         "timestamp":1457452214606
      },
      {
         "data":23.645000457763672,
         "timestamp":1457452814605
      },
      {
         "data":24.00749969482422,
         "timestamp":1457453414605
      },
      {
         "data":23.850000381469727,
         "timestamp":1457454014605
      },
      {
         "data":23.697500228881836,
         "timestamp":1457454614605
      },
      {
         "data":23.704999923706055,
         "timestamp":1457455214605
      },
      {
         "data":23.825000762939453,
         "timestamp":1457455814605
      },
      {
         "data":23.704999923706055,
         "timestamp":1457456414605
      },
      {
         "data":23.75,
         "timestamp":1457457014605
      },
Figure 3. Get Energy Optimization Advice Details: Response (Part 2)

      {
         "data":23.704999923706055,
         "timestamp":1457457614605
      },
      {
         "data":23.7450008392334,
         "timestamp":1457458214605
      },
      {
         "data":23.78499984741211,
         "timestamp":1457458814606
      },
      {
         "data":23.834999084472656,
         "timestamp":1457459414607
      },
      {
         "data":23.795000076293945,
         "timestamp":1457460014606
      },
      {
         "data":23.912500381469727,
         "timestamp":1457460614604
      },
      {
         "data":23.80500030517578,
         "timestamp":1457461214606
      },
      {
         "data":23.6875,
         "timestamp":1457461814606
      },
      {
         "data":23.799999237060547,
         "timestamp":1457462414604
      },
      {
         "data":23.889999389648438,
         "timestamp":1457463014605
      },
      {
         "data":23.907499313354492,
         "timestamp":1457463614604
      },
      {
         "data":23.877500534057617,
         "timestamp":1457464214614
      },
      {
         "data":24.012500762939453,
         "timestamp":1457464814605
      },
Figure 4. Get Energy Optimization Advice Details: Response (Part 3)
      {
         "data":24.200000762939453,
         "timestamp":1457465414604
      }
   ],
   "temperature-threshold":23.0,
   "timestamp":1457031003347,
   "type":"environmental",
   "wattage":6952,
   "wattage-graph":[
      {
         "data":6957,
         "timestamp":1457451614605
      },
      {
         "data":6970,
         "timestamp":1457452214606
      },
      {
         "data":6968,
         "timestamp":1457452814605
      },
      {
         "data":6970,
         "timestamp":1457453414605
      },
      {
         "data":6965,
         "timestamp":1457454014605
      },
      {
         "data":6970,
         "timestamp":1457454614605
      },
      {
         "data":6965,
         "timestamp":1457455214605
      },
      {
         "data":6963,
         "timestamp":1457455814605
      },
      {
         "data":6958,
         "timestamp":1457456414605
      },
      {
         "data":6969,
         "timestamp":1457457014605
      },
      {
         "data":6963,
         "timestamp":1457457614605
      },
Figure 5. Get Energy Optimization Advice Details: Response (Part 4)
      {
         "data":6963,
         "timestamp":1457458214605
      },
      {
         "data":6967,
         "timestamp":1457458814606
      },
      {
         "data":6961,
         "timestamp":1457459414607
      },
      {
         "data":6967,
         "timestamp":1457460014606
      },
      {
         "data":6963,
         "timestamp":1457460614604
      },
      {
         "data":6968,
         "timestamp":1457461214606
      },
      {
         "data":6969,
         "timestamp":1457461814606
      },
      {
         "data":6964,
         "timestamp":1457462414604
      },
      {
         "data":6963,
         "timestamp":1457463014605
      },
      {
         "data":6951,
         "timestamp":1457463614604
      },
      {
         "data":6941,
         "timestamp":1457464214614
      },
      {
         "data":6947,
         "timestamp":1457464814605
      },
      {
         "data":6955,
         "timestamp":1457465414604
      }
   ]
}