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
Custom metrics are in addition to the built-in (and standardized) metrics for VMs, and the platform can display both built-in and custom metrics in the UI at the VM and VApp group levels. See VM monitoring and metrics and Monitor virtual appliances. 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:
{
"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:
{
"links":[
{
"title":"metric0",
"rel":"metric",
"type":"application/vnd.abiquo.metric+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1/metrics/metric0"
},
{
"title":"metric0",
"rel":"self",
"type":"application/vnd.abiquo.metricmetadata+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1/metrics/metric0"
},
{
"title":"rack",
"rel":"rack",
"type":"application/vnd.abiquo.rack+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1"
}
],
"name":"metric0",
"description":"blablablabla",
"unit":"percent",
"namespace":"rack",
"dimensions":{
}
}
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".
curl -X GET http://localhost:80/api/admin/datacenters/1/racks/1/metrics \
-H 'Accept:application/vnd.abiquo.metricsmetadata+json; version=4.2' \
-u user:password --verbose
In this example, the response would be as follows.
{
"links":[
{
"title":"rack",
"rel":"rack",
"type":"application/vnd.abiquo.rack+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1"
},
{
"title":"metricsmetadata",
"rel":"self",
"type":"application/vnd.abiquo.metricsmetadata+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1/metrics"
}
],
"collection":[
{
"links":[
{
"title":"rack",
"rel":"rack",
"type":"application/vnd.abiquo.rack+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1"
},
{
"title":"metric0",
"rel":"metric",
"type":"application/vnd.abiquo.metric+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1/metrics/metric0"
},
{
"title":"metric0",
"rel":"self",
"type":"application/vnd.abiquo.metricmetadata+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1/metrics/metric0"
}
],
"name":"metric0",
"description":"blablablabla",
"unit":"percent",
"namespace":"rack",
"dimensions":{
}
}
]
}
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.
curl -X PUT http://localhost:9000/api/admin/datacenters/5267/racks/1525/metrics/metric0 \
-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
You can only edit the unit and the description. For example, you could send the following requestpayload object.
{
"name" : "metric0",
"namespace" : "rack",
"unit" : "percentage",
"description" : "bliblibli"
}
And an example response would be as follows:
{
"links":[
{
"title":"metric0",
"rel":"metric",
"type":"application/vnd.abiquo.metric+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1/metrics/metric0"
},
{
"title":"metric0",
"rel":"self",
"type":"application/vnd.abiquo.metricmetadata+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1/metrics/metric0"
},
{
"title":"rack",
"rel":"rack",
"type":"application/vnd.abiquo.rack+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1"
}
],
"name":"metric0",
"description":"bliblibli",
"unit":"percentage",
"namespace":"rack",
"dimensions":{
}
}
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”.
curl -X POST http://localhost:9000/api/admin/datacenters/1/racks/1/metrics/metric0 \
-H 'Accept:text/json,application/json' \
-H 'Content-Type:application/vnd.abiquo.datapoints+json; version=4.2' \
-d @requestpayload.json \
-u user:password --verbose
An example of metric datapoints to send as the requestpayload might be:
{
"collection" : [
{ "timestamp" : 1503580909513, "value" : 2.0 },
{ "timestamp" : 1503580910513, "value" : 4.0 }
]
}
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 |
|---|---|---|
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:
curl -X GET http://localhost:9000/api/admin/datacenters/1/racks/1/metrics/metric0 \
-H 'Accept:application/vnd.abiquo.metric+json; version=4.2' \
-u user:password --verbose
With the following response example:
{
"links":[
{
"title":"metric0",
"rel":"metricmetadata",
"type":"application/vnd.abiquo.metricmetadata+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1/metrics/metric0"
},
{
"title":"metric0",
"rel":"self",
"type":"application/vnd.abiquo.metric+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1/metrics/metric0"
},
{
"title":"rack",
"rel":"rack",
"type":"application/vnd.abiquo.rack+json",
"href":"http://localhost:80/api/admin/datacenters/1/racks/1"
}
],
"name":"metric0",
"namespace":"rack",
"unit":"percentage",
"description":"bliblibli",
"datapoints":{
"average":[
{
"links":[
],
"timestamp":1503580909513,
"value":3.0
}
]
}
}