Custom metrics resources

Author: Enric Ruiz

Abiquo enables you to easily manage custom metrics for many platform resources, including:

Public cloud region (from cloud/locations and admin/publiccloudregions)
Datacenter (from cloud/locations and admin/datacenters)
Machine
Rack
Virtual appliance
Scaling group
- Virtual machines
Virtual machine
Services

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, https://abiquo.atlassian.net/wiki/spaces/doc/pages/311370429 , and https://abiquo.atlassian.net/wiki/spaces/doc/pages/406749204. 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

1 API endpoints for custom metrics
2 Metricmetadata object
3 Create metric metadata
4 List metadata for all metrics
5 Update metric metadata
6 Push metric data points
7 Push collectd value lists
8 Get metric statistics

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:

{
    "href" : "http://localhost:80/api/admin/datacenters/1/racks/1/metrics",
    "type" : "application/vnd.abiquo.metricsmetadata+json",
    "rel" : "metricsmetadata",
    "title" : "metricsmetadata"
}
{
    "href": http://localhost:80/api/admin/datacenters/1/racks/1/metrics/collectd",
    "type" : "application/json",
    "title" : "collectd",
    "rel" : "collectd"
}

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.

curl -X POST http://localhost:80/api/admin/datacenters/1/racks/1/metrics \
     -H 'Accept:application/vnd.abiquo.metricmetadata+json; version=4.2' \
     -H 'Content-Type:application/vnd.abiquo.metricmetadata+json; version=4.2' \
     -d @requestpayload.json \
     -u user:password --verbose

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.

{
   "name" : "metric0",
   "namespace" : "rack",
   "unit" : "percent",
   "description" : "blablablabla"
}

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.

Parameter	Description	Default value

Parameter	Description	Default value
startrelative	Relative start time following the ISO 8601 duration (cannot contain years or months). A maximum of 1 week.	PT1H (1 Hour)
granularity	Aggregator granularity in seconds. A minimum of 60 seconds.	60 seconds
statistic	Aggregator type { average, maximum, minimum, sum, count, dev }	average

The basic query would be as follows:

With the following response example: