Abiquo Documentation Cookies Policy

Our Documentation website uses cookies to improve your experience. Please visit our Cookie Policy page for more information about cookies and how we use them.


Abiquo Documentation

Skip to end of metadata
Go to start of metadata

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 machine

API endpoints

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
         }
      ]
   }
}


 

  • No labels