Custom metrics resources

Author: Enric Ruiz

Custom metrics are in addition to the built-in (and standardized) metrics for VMs and services. In the UI, the platform can display built-in and custom metrics for VMs at the VM and VApp group levels, and for services. See VM monitoring and metrics, Manage virtual appliances , and Service metrics. The platform can evaluate all metrics as part of alarms, for a description of alarm functionality in the UI, see Manage cloud alarms and Infrastructure alarms. In this way the user can also incorporate the metrics into alerts and use them to trigger action plans, for example, to automate scaling.

Contents

API endpoints for custom metrics

The entities that support custom metric management provide two links:

• Link with a "rel" value of “metricsmetadata” to retrieve the all available metric metadata for the entity

• Link with a "rel" value of “collectd” to push collectd value lists

For example, for a rack, the links are:

Each metricmetadata object describes an existing metric, so if the user has not created any custom metrics for non-VM objects, then metricsmetadata will be any empty collection.

Metricmetadata object

The metricmetadata object can contain the following attributes:

• Name

• Description

• Unit

• Namespace

• Dimensions

It is possible to populate a metric without metadata. In this case, the API automatically creates basic metadata with the name and namespace. 

Metric dimensions are read-only and they are automatically filled when users data points to the metric. Users can update the metadata through the API at any time.

Create metric metadata

To create metric metadata, send a POST request to the link with the "rel" value of "metricsmetadata". To continue with the rack example.

The request data object should be a "metricmetadata" object, such as the following. Note that the "namespace" attribute is optional and is overwritten by the API.

The example response would look as follows:

Three links are provided in this response:

• Link with a "rel" value of “metric” that you can query to obtain metric statistics

• Link with a "rel" value of “self” that you can query about this metric's metadata

• Link to the parent (or owner) of the metric, for example, a rack

List metadata for all metrics

To retrieve metrics metadata, send a GET request to the link with the "rel" value of "metricsmetadata". 

In this example, the response would be as follows.

Update metric metadata

You can update the unit and description of custom metric metadata. Find the link to the specific metric and send a PUT request to the URI specified by the "href" attribute with the content type indicated by the "type" attribute. 

You can only edit the unit and the description. For example, you could send the following requestpayload object. 

And an example response would be as follows:

Push metric data points

Given the metadata of a metric, search for the link with “rel” attribute value equal to “metric” and execute a POST to the URI specified by “href” attribute with the content type “application/vnd.abiquo.datapoints+json”. 

An example of metric datapoints to send as the requestpayload might be:

A successful request will return a status code of 204 with no content.

Push collectd value lists

Search for the link with “rel” attribute with a value equal to a “collectd” and send a POST to the URI specified by “href” attribute with the content type indicated in the “type” attribute and a PUTVAL JSON format as content.

See https://collectd.org/wiki/index.php/Plugin:Write_HTTP#JSON_Example for an example of valid request content.

Abiquo’s collectd writer plugin (see https://github.com/abiquo/collectd-abiquo) is designed to push values to the API in this way.

Get metric statistics

Given the metadata of a metric, search the link with “rel” attribute value equals to “metric” and execute a GET to the URI specified by “href” attribute with the accept type indicated in the “type” attribute.

The basic query would be as follows:

With the following response example: