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:
If not specified, the default is "one-day". |
type | String Enum | Required | The type of advice details to return. Valid
values are:
|
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:
|
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":
When type is "processor-utilization":
|
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:
|
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:
|
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
- 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.
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.