Create Metrics Context
The Create Metrics Context operation creates a context under which metrics can be repeatedly retrieved. This context will be associated with the API session under which it was created.
HTTP method and URI
POST /api/services/metrics/context
Request body contents
A request body must be specified. It has the following fields:
Field name | Type | Description |
---|---|---|
anticipated-frequency-seconds | Integer | The number of seconds the client anticipates will elapse between Get Metrics calls against this context. The minimum accepted value is 15. |
metric-groups | Array of Strings | Optional. Array of metric group names. If specified, then results from future Get Metrics requests associated with this context will be limited to only metrics with group names matching one of the specified values. If not specified, or if an empty array is specified, then results will not be limited with respect to metric group names. |
Response body contents
On successful completion, the response body contains a JSON object with the following fields:
Field name | Type | Description |
---|---|---|
metrics-context-uri | String/ URI | Canonical URI path of the metrics context object created by this operation
This includes the metrics-context-id. E.g. /api/services/metrics/context/1, where 1is the metrics-context-id. |
metric-group-infos | Array of objects | Array of metric-group-info objects (described in the next table) that describe the data format for each metric group that may be returned by future GETs associated with this metric context. |
Each nested metric-group-info object contains the following fields:
Field name | Type | Description |
---|---|---|
group-name | String | The name of the metric group for which we are providing descriptive information. |
metric-infos | Array | Array of metric-info objects (described in the next table). These describe each metric for the group in the order that they will appear in future GETs associated with this context. |
Each nested metric-info object contains the following fields:
Field name | Type | Description |
---|---|---|
metric-name | String | The name of the metric. |
metric-type | String Enum | One of the following, describing the type of
the metric: "boolean-metric", "byte-metric", "double-metric", "long-metric", "integer-metric", "short-metric", "string-metric" See the Get Metrics Response body contents for further information on these metric types. |
Description
This operation establishes a context for future Get Metrics operations that is valid for the current API session. Because of the high frequency of invocation and large volume of data expected, the metrics service interface has been structured to optimize the transmission of data on each Get Metrics request. Thus, rather than use a self-describing representation for the results returned by each Get Metrics, the metrics service instead provides the descriptive metadata as results from this Create Metrics Context operation. It then returns the metric data in a compact format each time Get Metrics is invoked.
At a high level, the Create Metrics Context response communicates two primary pieces of information back to the client. One is the metrics-context-uri, which includes the ID of the metrics context that must be referenced on future GETs to associate them with this context. The other is the metric-groups description data. That data provides the metric type and metric name information for each metric group whose metrics may be returned by this context. This may be useful to the client for determining how to parse future Get Metrics responses for this context, although the full documentation on metric group formats is found in Metric groups.
The anticipated-frequency-seconds specification which is required on the request body tells the metrics service how frequently the client anticipates issuing Get Metrics requests against this context. The metrics service may take no action based on this frequency, but reserves the right to invalidate and delete the metrics context if 4 times the specified frequency passes without receipt of an associated Get Metrics operation.
Optional result filtering is provided by field metric-groups on the request body. If a non-empty metric-groups arrays is specified, then future Get Metrics operations associated with this context will return only groups with names listed there.
Additionally, if a metric-groups array of group names is specified on the Create Metrics Context request, then the response JSON document will include only matching metric-group-info fields. If one or more names in the metric-groups array does not represent a metric group registered on the HMC, then HTTP error status code 400 (Bad Request) will be returned and the context will not be established.
Although the POST response fully describes and guarantees the ordering of metric-infos within a metric group for that context, as a matter of policy the HMC will further guarantee that, for a given metric group, any additions of new metrics to the group will be to the end of the list for the group.
Authorization requirements
There are no authorization restrictions on creating a metrics context. However any future metric results returned by Get Metrics queries against that context will be restricted to managed objects accessible according to the permissions associated with the API session under which the metrics context was established.
Note that there is no indication through an HTTP status or reason code that future results may be restricted due to authorization restrictions. Rather, success is indicated and future Get Metrics responses behave just as if any restricted objects did not exist.
HTTP status and reason codes
On success, HTTP status code 201 (Created) is returned and the response body is provided as described in Response body contents. The URI for the newly created context is also provided in the Location header of the response.
The following HTTP status codes are returned for the indicated errors, and 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. See Common request validation reason codes for a list of the possible reason codes. |
Additional standard status and reason codes can be returned, as described in Invoking API operations.