================
 REST API Usage
================

Authentication
==============

By default, no authentication is configured in Gnocchi. You need to provides
these headers in your HTTP requests:

* X-User-Id
* X-Project-Id

The `X-Roles` header can also be provided in order to match role based ACL
specified in `policy.json`, as `X-Domain-Id` to match domain based ACL.

If you enable the OpenStack Keystone middleware, you only need to authenticate
against Keystone and provide `X-Auth-Token` header with a valid token for each
request sent to Gnocchi. The headers mentioned above will be filled
automatically based on your Keystone authorizations.

Metrics
=======

Gnocchi provides an object type that is called *metric*. A metric designates
any thing that can be measured: the CPU usage of a server, the temperature of a
room or the number of bytes sent by a network interface.

A metric only has a few properties: a UUID to identify it, a name, the archive
policy that will be used to store and aggregate the measures.

To create a metric, the following API request should be used:


   .. sourcecode:: http

      POST /v1/metric HTTP/1.1
      Content-Type: application/json
      Content-Length: 35

      {
        "archive_policy_name": "high"
      }

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Location: http://localhost/v1/metric/bc3b6971-7cb8-4019-a36d-850f3f954ebb
      Content-Length: 253
      Content-Type: application/json; charset=UTF-8

      {
        "archive_policy_name": "high", 
        "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
        "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
        "id": "bc3b6971-7cb8-4019-a36d-850f3f954ebb", 
        "name": null, 
        "resource_id": null, 
        "unit": null
      }

Once created, you can retrieve the metric information:


   .. sourcecode:: http

      GET /v1/metric/bc3b6971-7cb8-4019-a36d-850f3f954ebb HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 598
      Content-Type: application/json; charset=UTF-8

      {
        "archive_policy": {
          "aggregation_methods": [
            "std", 
            "count", 
            "95pct", 
            "min", 
            "max", 
            "sum", 
            "median", 
            "mean"
          ], 
          "back_window": 0, 
          "definition": [
            {
              "granularity": "0:00:01", 
              "points": 3600, 
              "timespan": "1:00:00"
            }, 
            {
              "granularity": "0:01:00", 
              "points": 10080, 
              "timespan": "7 days, 0:00:00"
            }, 
            {
              "granularity": "1:00:00", 
              "points": 8760, 
              "timespan": "365 days, 0:00:00"
            }
          ], 
          "name": "high"
        }, 
        "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
        "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
        "id": "bc3b6971-7cb8-4019-a36d-850f3f954ebb", 
        "name": null, 
        "resource": null, 
        "unit": null
      }

To retrieve the list of all the metrics created, use the following request:


   .. sourcecode:: http

      GET /v1/metric HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 1203
      Content-Type: application/json; charset=UTF-8

      [
        {
          "archive_policy": {
            "aggregation_methods": [
              "std", 
              "count", 
              "95pct", 
              "min", 
              "max", 
              "sum", 
              "median", 
              "mean"
            ], 
            "back_window": 0, 
            "definition": [
              {
                "granularity": "0:05:00", 
                "points": 12, 
                "timespan": "1:00:00"
              }, 
              {
                "granularity": "1:00:00", 
                "points": 24, 
                "timespan": "1 day, 0:00:00"
              }, 
              {
                "granularity": "1 day, 0:00:00", 
                "points": 30, 
                "timespan": "30 days, 0:00:00"
              }
            ], 
            "name": "low"
          }, 
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "id": "01e29d68-7603-4c97-a976-4900c1c7cebf", 
          "name": null, 
          "resource_id": null, 
          "unit": null
        }, 
        {
          "archive_policy": {
            "aggregation_methods": [
              "std", 
              "count", 
              "95pct", 
              "min", 
              "max", 
              "sum", 
              "median", 
              "mean"
            ], 
            "back_window": 0, 
            "definition": [
              {
                "granularity": "0:00:01", 
                "points": 3600, 
                "timespan": "1:00:00"
              }, 
              {
                "granularity": "0:01:00", 
                "points": 10080, 
                "timespan": "7 days, 0:00:00"
              }, 
              {
                "granularity": "1:00:00", 
                "points": 8760, 
                "timespan": "365 days, 0:00:00"
              }
            ], 
            "name": "high"
          }, 
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "id": "bc3b6971-7cb8-4019-a36d-850f3f954ebb", 
          "name": null, 
          "resource_id": null, 
          "unit": null
        }
      ]

.. note::

  Considering the large volume of metrics Gnocchi will store, query results are
  limited to `max_limit` value set in the configuration file. Returned results
  are ordered by metrics' id values. To retrieve the next page of results, the
  id of a metric should be given as `marker` for the beginning of the next page
  of results.

Default ordering and limits as well as page start can be modified
using query parameters:


   .. sourcecode:: http

      GET /v1/metric?limit=100&sort=name:asc HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 1203
      Content-Type: application/json; charset=UTF-8

      [
        {
          "archive_policy": {
            "aggregation_methods": [
              "std", 
              "count", 
              "95pct", 
              "min", 
              "max", 
              "sum", 
              "median", 
              "mean"
            ], 
            "back_window": 0, 
            "definition": [
              {
                "granularity": "0:05:00", 
                "points": 12, 
                "timespan": "1:00:00"
              }, 
              {
                "granularity": "1:00:00", 
                "points": 24, 
                "timespan": "1 day, 0:00:00"
              }, 
              {
                "granularity": "1 day, 0:00:00", 
                "points": 30, 
                "timespan": "30 days, 0:00:00"
              }
            ], 
            "name": "low"
          }, 
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "id": "01e29d68-7603-4c97-a976-4900c1c7cebf", 
          "name": null, 
          "resource_id": null, 
          "unit": null
        }, 
        {
          "archive_policy": {
            "aggregation_methods": [
              "std", 
              "count", 
              "95pct", 
              "min", 
              "max", 
              "sum", 
              "median", 
              "mean"
            ], 
            "back_window": 0, 
            "definition": [
              {
                "granularity": "0:00:01", 
                "points": 3600, 
                "timespan": "1:00:00"
              }, 
              {
                "granularity": "0:01:00", 
                "points": 10080, 
                "timespan": "7 days, 0:00:00"
              }, 
              {
                "granularity": "1:00:00", 
                "points": 8760, 
                "timespan": "365 days, 0:00:00"
              }
            ], 
            "name": "high"
          }, 
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "id": "bc3b6971-7cb8-4019-a36d-850f3f954ebb", 
          "name": null, 
          "resource_id": null, 
          "unit": null
        }
      ]

It is possible to send measures to the metric:


   .. sourcecode:: http

      POST /v1/metric/bc3b6971-7cb8-4019-a36d-850f3f954ebb/measures HTTP/1.1
      Content-Type: application/json
      Content-Length: 198

      [
        {
          "timestamp": "2014-10-06T14:33:57", 
          "value": 43.1
        }, 
        {
          "timestamp": "2014-10-06T14:34:12", 
          "value": 12
        }, 
        {
          "timestamp": "2014-10-06T14:34:20", 
          "value": 2
        }
      ]

   .. sourcecode:: http

      HTTP/1.1 202 Accepted
      Content-Length: 0
      Content-Type: text/html; charset=UTF-8

      

If there are no errors, Gnocchi does not return a response body, only a simple
status code. It is possible to provide any number of measures.

.. IMPORTANT::

   While it is possible to send any number of (timestamp, value), it is still
   needed to honor constraints defined by the archive policy used by the metric,
   such as the maximum timespan.


Once measures are sent, it is possible to retrieve them using *GET* on the same
endpoint:


   .. sourcecode:: http

      GET /v1/metric/bc3b6971-7cb8-4019-a36d-850f3f954ebb/measures HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 297
      Content-Type: application/json; charset=UTF-8

      [
        [
          "2014-10-06T14:00:00+00:00", 
          3600.0, 
          19.033333333333335
        ], 
        [
          "2014-10-06T14:33:00+00:00", 
          60.0, 
          43.1
        ], 
        [
          "2014-10-06T14:34:00+00:00", 
          60.0, 
          7.0
        ], 
        [
          "2014-10-06T14:33:57+00:00", 
          1.0, 
          43.1
        ], 
        [
          "2014-10-06T14:34:12+00:00", 
          1.0, 
          12.0
        ], 
        [
          "2014-10-06T14:34:20+00:00", 
          1.0, 
          2.0
        ]
      ]

Depending on the driver, there may be some lag after POSTing measures before
they are processed and queryable. To ensure your query returns all measures
that have been POSTed, you can force any unprocessed measures to be handled:


   .. sourcecode:: http

      GET /v1/metric/bc3b6971-7cb8-4019-a36d-850f3f954ebb/measures?refresh=true HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 297
      Content-Type: application/json; charset=UTF-8

      [
        [
          "2014-10-06T14:00:00+00:00", 
          3600.0, 
          19.033333333333335
        ], 
        [
          "2014-10-06T14:33:00+00:00", 
          60.0, 
          43.1
        ], 
        [
          "2014-10-06T14:34:00+00:00", 
          60.0, 
          7.0
        ], 
        [
          "2014-10-06T14:33:57+00:00", 
          1.0, 
          43.1
        ], 
        [
          "2014-10-06T14:34:12+00:00", 
          1.0, 
          12.0
        ], 
        [
          "2014-10-06T14:34:20+00:00", 
          1.0, 
          2.0
        ]
      ]

.. note::

   Depending on the amount of data that is unprocessed, `refresh` may add
   some overhead to your query.

The list of points returned is composed of tuples with (timestamp, granularity,
value) sorted by timestamp. The granularity is the timespan covered by
aggregation for this point.

It is possible to filter the measures over a time range by specifying the
*start* and/or *stop* parameters to the query with timestamp. The timestamp
format can be either a floating number (UNIX epoch) or an ISO8601 formated
timestamp:


   .. sourcecode:: http

      GET /v1/metric/bc3b6971-7cb8-4019-a36d-850f3f954ebb/measures?start=2014-10-06T14:34 HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 184
      Content-Type: application/json; charset=UTF-8

      [
        [
          "2014-10-06T14:00:00+00:00", 
          3600.0, 
          19.033333333333335
        ], 
        [
          "2014-10-06T14:34:00+00:00", 
          60.0, 
          7.0
        ], 
        [
          "2014-10-06T14:34:12+00:00", 
          1.0, 
          12.0
        ], 
        [
          "2014-10-06T14:34:20+00:00", 
          1.0, 
          2.0
        ]
      ]

By default, the aggregated values that are returned use the *mean* aggregation
method. It is possible to request for any other method by specifying the
*aggregation* query parameter:


   .. sourcecode:: http

      GET /v1/metric/bc3b6971-7cb8-4019-a36d-850f3f954ebb/measures?aggregation=max HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 298
      Content-Type: application/json; charset=UTF-8

      [
        [
          "2014-10-06T14:00:00+00:00", 
          3600.0, 
          43.1
        ], 
        [
          "2014-10-06T14:33:00+00:00", 
          60.0, 
          43.1
        ], 
        [
          "2014-10-06T14:34:00+00:00", 
          60.0, 
          12.0
        ], 
        [
          "2014-10-06T14:33:57+00:00", 
          1.0, 
          43.1
        ], 
        [
          "2014-10-06T14:34:12+00:00", 
          1.0, 
          12.0
        ], 
        [
          "2014-10-06T14:34:20+00:00", 
          1.0, 
          2.0
        ]
      ]

The list of aggregation method available is: *mean*, *sum*, *last*, *max*,
*min*, *std*, *median*, *first*, *count* and *Npct* (with 0 < N < 100).

It's possible to provide the `granularity` argument to specify the granularity
to retrieve, rather than all the granularities available:


   .. sourcecode:: http

      GET /v1/metric/bc3b6971-7cb8-4019-a36d-850f3f954ebb/measures?granularity=1 HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 139
      Content-Type: application/json; charset=UTF-8

      [
        [
          "2014-10-06T14:33:57+00:00", 
          1.0, 
          43.1
        ], 
        [
          "2014-10-06T14:34:12+00:00", 
          1.0, 
          12.0
        ], 
        [
          "2014-10-06T14:34:20+00:00", 
          1.0, 
          2.0
        ]
      ]


Measures batching
=================
It is also possible to batch measures sending, i.e. send several measures for
different metrics in a simple call:


   .. sourcecode:: http

      POST /v1/batch/metrics/measures HTTP/1.1
      Content-Type: application/json
      Content-Length: 391

      {
        "01e29d68-7603-4c97-a976-4900c1c7cebf": [
          {
            "timestamp": "2014-10-06T16:12:12", 
            "value": 3
          }, 
          {
            "timestamp": "2014-10-06T18:14:52", 
            "value": 4
          }
        ], 
        "bc3b6971-7cb8-4019-a36d-850f3f954ebb": [
          {
            "timestamp": "2014-10-06T14:34:12", 
            "value": 12
          }, 
          {
            "timestamp": "2014-10-06T14:34:20", 
            "value": 2
          }
        ]
      }

   .. sourcecode:: http

      HTTP/1.1 202 Accepted
      Content-Length: 0
      Content-Type: text/html; charset=UTF-8

      

Or using named metrics of resources:


   .. sourcecode:: http

      POST /v1/batch/resources/metrics/measures HTTP/1.1
      Content-Type: application/json
      Content-Length: 585

      {
        "15e9c872-7ca9-11e4-a2da-2fb4032dfc09": {
          "cpu.util": [
            {
              "timestamp": "2014-10-06T14:34:12", 
              "value": 12
            }, 
            {
              "timestamp": "2014-10-06T14:34:20", 
              "value": 2
            }
          ]
        }, 
        "6f24edd9-5a2f-4592-b708-ffbed821c5d2": {
          "cpu.util": [
            {
              "timestamp": "2014-10-06T14:34:12", 
              "value": 6
            }, 
            {
              "timestamp": "2014-10-06T14:34:20", 
              "value": 25
            }
          ]
        }, 
        "ab68da77-fa82-4e67-aba9-270c5a98cbcb": {
          "temperature": [
            {
              "timestamp": "2014-10-06T14:34:12", 
              "value": 17
            }, 
            {
              "timestamp": "2014-10-06T14:34:20", 
              "value": 18
            }
          ]
        }
      }

   .. sourcecode:: http

      HTTP/1.1 202 Accepted
      Content-Length: 0
      Content-Type: text/html; charset=UTF-8

      


Archive Policy
==============

When sending measures for a metric to Gnocchi, the values are dynamically
aggregated. That means that Gnocchi does not store all sent measures, but
aggregates them over a certain period of time. Gnocchi provides several
aggregation methods (mean, min, max, sum…) that are builtin.

An archive policy is defined by a list of items in the `definition` field. Each
item is composed of the timespan and the level of precision that must be kept
when aggregating data, determined using at least 2 of the `points`,
`granularity` and `timespan` fields. For example, an item might be defined
as 12 points over 1 hour (one point every 5 minutes), or 1 point every 1 hour
over 1 day (24 points).

By default, new measures can only be processed if they have timestamps in the
future or part of the last aggregation period. The last aggregation period size
is based on the largest granularity defined in the archive policy definition.
To allow processing measures that are older than the period, the `back_window`
parameter can be used to set the number of coarsest periods to keep. That way
it is possible to process measures that are older than the last timestamp
period boundary.

For example, if an archive policy is defined with coarsest aggregation of 1
hour, and the last point processed has a timestamp of 14:34, it's possible to
process measures back to 14:00 with a `back_window` of 0. If the `back_window`
is set to 2, it will be possible to send measures with timestamp back to 12:00
(14:00 minus 2 times 1 hour).

The REST API allows to create archive policies in this way:


   .. sourcecode:: http

      POST /v1/archive_policy HTTP/1.1
      Content-Type: application/json
      Content-Length: 189

      {
        "back_window": 0, 
        "definition": [
          {
            "granularity": "1s", 
            "timespan": "1 hour"
          }, 
          {
            "points": 48, 
            "timespan": "1 day"
          }
        ], 
        "name": "short"
      }

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Location: http://localhost/v1/archive_policy/short
      Content-Length: 279
      Content-Type: application/json; charset=UTF-8

      {
        "aggregation_methods": [
          "std", 
          "count", 
          "95pct", 
          "min", 
          "max", 
          "sum", 
          "median", 
          "mean"
        ], 
        "back_window": 0, 
        "definition": [
          {
            "granularity": "0:00:01", 
            "points": 3600, 
            "timespan": "1:00:00"
          }, 
          {
            "granularity": "0:30:00", 
            "points": 48, 
            "timespan": "1 day, 0:00:00"
          }
        ], 
        "name": "short"
      }

By default, the aggregation methods computed and stored are the ones defined
with `default_aggregation_methods` in the configuration file. It is possible to
change the aggregation methods used in an archive policy by specifying the list
of aggregation method to use in the `aggregation_methods` attribute of an
archive policy.


   .. sourcecode:: http

      POST /v1/archive_policy HTTP/1.1
      Content-Type: application/json
      Content-Length: 244

      {
        "aggregation_methods": [
          "-max", 
          "-min"
        ], 
        "back_window": 0, 
        "definition": [
          {
            "granularity": "1s", 
            "timespan": "1 hour"
          }, 
          {
            "points": 48, 
            "timespan": "1 day"
          }
        ], 
        "name": "short-without-max"
      }

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Location: http://localhost/v1/archive_policy/short-without-max
      Content-Length: 277
      Content-Type: application/json; charset=UTF-8

      {
        "aggregation_methods": [
          "std", 
          "count", 
          "95pct", 
          "sum", 
          "median", 
          "mean"
        ], 
        "back_window": 0, 
        "definition": [
          {
            "granularity": "0:00:01", 
            "points": 3600, 
            "timespan": "1:00:00"
          }, 
          {
            "granularity": "0:30:00", 
            "points": 48, 
            "timespan": "1 day, 0:00:00"
          }
        ], 
        "name": "short-without-max"
      }

The list of aggregation methods can either be:

- a list of aggregation methods to use, e.g. `["mean", "max"]`

- a list of methods to remove (prefixed by `-`) and/or to add (prefixed by `+`)
  to the default list (e.g. `["+mean", "-last"]`)

If `*` is included in the list, it's substituted by the list of all supported
aggregation methods.

Once the archive policy is created, the complete set of properties is computed
and returned, with the URL of the archive policy. This URL can be used to
retrieve the details of the archive policy later:


   .. sourcecode:: http

      GET /v1/archive_policy/short HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 279
      Content-Type: application/json; charset=UTF-8

      {
        "aggregation_methods": [
          "std", 
          "count", 
          "95pct", 
          "min", 
          "max", 
          "sum", 
          "median", 
          "mean"
        ], 
        "back_window": 0, 
        "definition": [
          {
            "granularity": "0:00:01", 
            "points": 3600, 
            "timespan": "1:00:00"
          }, 
          {
            "granularity": "0:30:00", 
            "points": 48, 
            "timespan": "1 day, 0:00:00"
          }
        ], 
        "name": "short"
      }

It is also possible to list archive policies:


   .. sourcecode:: http

      GET /v1/archive_policy HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 1886
      Content-Type: application/json; charset=UTF-8

      [
        {
          "aggregation_methods": [
            "std", 
            "count", 
            "95pct", 
            "min", 
            "max", 
            "sum", 
            "median", 
            "mean"
          ], 
          "back_window": 0, 
          "definition": [
            {
              "granularity": "0:00:01", 
              "points": 3600, 
              "timespan": "1:00:00"
            }, 
            {
              "granularity": "0:01:00", 
              "points": 10080, 
              "timespan": "7 days, 0:00:00"
            }, 
            {
              "granularity": "1:00:00", 
              "points": 8760, 
              "timespan": "365 days, 0:00:00"
            }
          ], 
          "name": "high"
        }, 
        {
          "aggregation_methods": [
            "std", 
            "count", 
            "95pct", 
            "min", 
            "max", 
            "sum", 
            "median", 
            "mean"
          ], 
          "back_window": 0, 
          "definition": [
            {
              "granularity": "0:00:02", 
              "points": 86400, 
              "timespan": "2 days, 0:00:00"
            }
          ], 
          "name": "no_granularity_match"
        }, 
        {
          "aggregation_methods": [
            "std", 
            "count", 
            "95pct", 
            "min", 
            "max", 
            "sum", 
            "median", 
            "mean"
          ], 
          "back_window": 0, 
          "definition": [
            {
              "granularity": "0:01:00", 
              "points": 1440, 
              "timespan": "1 day, 0:00:00"
            }, 
            {
              "granularity": "1:00:00", 
              "points": 168, 
              "timespan": "7 days, 0:00:00"
            }, 
            {
              "granularity": "1 day, 0:00:00", 
              "points": 365, 
              "timespan": "365 days, 0:00:00"
            }
          ], 
          "name": "medium"
        }, 
        {
          "aggregation_methods": [
            "std", 
            "count", 
            "95pct", 
            "min", 
            "max", 
            "sum", 
            "median", 
            "mean"
          ], 
          "back_window": 0, 
          "definition": [
            {
              "granularity": "0:05:00", 
              "points": 12, 
              "timespan": "1:00:00"
            }, 
            {
              "granularity": "1:00:00", 
              "points": 24, 
              "timespan": "1 day, 0:00:00"
            }, 
            {
              "granularity": "1 day, 0:00:00", 
              "points": 30, 
              "timespan": "30 days, 0:00:00"
            }
          ], 
          "name": "low"
        }, 
        {
          "aggregation_methods": [
            "std", 
            "count", 
            "95pct", 
            "min", 
            "max", 
            "sum", 
            "median", 
            "mean"
          ], 
          "back_window": 0, 
          "definition": [
            {
              "granularity": "0:00:01", 
              "points": 3600, 
              "timespan": "1:00:00"
            }, 
            {
              "granularity": "0:30:00", 
              "points": 48, 
              "timespan": "1 day, 0:00:00"
            }
          ], 
          "name": "short"
        }, 
        {
          "aggregation_methods": [
            "std", 
            "count", 
            "95pct", 
            "sum", 
            "median", 
            "mean"
          ], 
          "back_window": 0, 
          "definition": [
            {
              "granularity": "0:00:01", 
              "points": 3600, 
              "timespan": "1:00:00"
            }, 
            {
              "granularity": "0:30:00", 
              "points": 48, 
              "timespan": "1 day, 0:00:00"
            }
          ], 
          "name": "short-without-max"
        }
      ]

Existing archive policies can be modified to retain more or less data depending
on requirements. If the policy coverage is expanded, measures are not
retroactively calculated as backfill to accommodate the new timespan:


   .. sourcecode:: http

      PATCH /v1/archive_policy/short HTTP/1.1
      Content-Type: application/json
      Content-Length: 150

      {
        "definition": [
          {
            "granularity": "1s", 
            "timespan": "1 hour"
          }, 
          {
            "points": 48, 
            "timespan": "1 day"
          }
        ]
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 279
      Content-Type: application/json; charset=UTF-8

      {
        "aggregation_methods": [
          "std", 
          "count", 
          "95pct", 
          "min", 
          "max", 
          "sum", 
          "median", 
          "mean"
        ], 
        "back_window": 0, 
        "definition": [
          {
            "granularity": "0:00:01", 
            "points": 3600, 
            "timespan": "1:00:00"
          }, 
          {
            "granularity": "0:30:00", 
            "points": 48, 
            "timespan": "1 day, 0:00:00"
          }
        ], 
        "name": "short"
      }

.. note::

   Granularities cannot be changed to a different rate. Also, granularities
   cannot be added or dropped from a policy.

It is possible to delete an archive policy if it is not used by any metric:


   .. sourcecode:: http

      DELETE /v1/archive_policy/some-archive-policy HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 204 No Content
      Content-Length: 0

      

.. note::

   An archive policy cannot be deleted until all metrics associated with it
   are removed by a metricd daemon.


Archive Policy Rule
===================

Gnocchi provides the ability to define a mapping called `archive_policy_rule`.
An archive policy rule defines a mapping between a metric and an archive policy.
This gives users the ability to pre-define rules so an archive policy is assigned to
metrics based on a matched pattern.

An archive policy rule has a few properties: a name to identify it, an archive
policy name that will be used to store the policy name and metric pattern to
match metric names.

An archive policy rule for example could be a mapping to default a medium archive
policy for any volume metric with a pattern matching `volume.*`. When a sample metric
is posted with a name of `volume.size`, that would match the pattern and the
rule applies and sets the archive policy to medium. If multiple rules match,
the longest matching rule is taken. For example, if two rules exists which
match `*` and `disk.*`, a `disk.io.rate` metric would match the `disk.*` rule
rather than `*` rule.

To create a rule, the following API request should be used:


   .. sourcecode:: http

      POST /v1/archive_policy_rule HTTP/1.1
      Content-Type: application/json
      Content-Length: 90

      {
        "archive_policy_name": "low", 
        "metric_pattern": "disk.io.*", 
        "name": "test_rule"
      }

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Location: http://localhost/v1/archive_policy_rule/test_rule
      Content-Length: 82
      Content-Type: application/json; charset=UTF-8

      {
        "archive_policy_name": "low", 
        "metric_pattern": "disk.io.*", 
        "name": "test_rule"
      }

The `metric_pattern` is used to pattern match so as some examples,

- `*` matches anything
- `disk.*` matches disk.io
- `disk.io.*` matches disk.io.rate

Once created, you can retrieve the rule information:


   .. sourcecode:: http

      GET /v1/archive_policy_rule/test_rule HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 82
      Content-Type: application/json; charset=UTF-8

      {
        "archive_policy_name": "low", 
        "metric_pattern": "disk.io.*", 
        "name": "test_rule"
      }

It is also possible to list archive policy rules. The result set is ordered by
the `metric_pattern`, in reverse alphabetical order:


   .. sourcecode:: http

      GET /v1/archive_policy_rule HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 84
      Content-Type: application/json; charset=UTF-8

      [
        {
          "archive_policy_name": "low", 
          "metric_pattern": "disk.io.*", 
          "name": "test_rule"
        }
      ]

It is possible to delete an archive policy rule:


   .. sourcecode:: http

      DELETE /v1/archive_policy_rule/test_rule_delete HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 204 No Content
      Content-Length: 0

      

Resources
=========

Gnocchi provides the ability to store and index resources. Each resource has a
type. The basic type of resources is *generic*, but more specialized subtypes
also exist, especially to describe OpenStack resources.

The REST API allows to manipulate resources. To create a generic resource:


   .. sourcecode:: http

      POST /v1/resource/generic HTTP/1.1
      Content-Type: application/json
      Content-Length: 159

      {
        "id": "75C44741-CC60-4033-804E-2D3098C7D2E9", 
        "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
        "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
      }

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Location: http://localhost/v1/resource/generic/75c44741-cc60-4033-804e-2d3098c7d2e9
      ETag: "c93e52f65a4369d8b350ca23777f7f14066eb685"
      Last-Modified: Tue, 01 Jun 2021 20:48:06 GMT
      Content-Length: 520
      Content-Type: application/json; charset=UTF-8

      {
        "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
        "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
        "ended_at": null, 
        "id": "75c44741-cc60-4033-804e-2d3098c7d2e9", 
        "metrics": {}, 
        "original_resource_id": "75C44741-CC60-4033-804E-2D3098C7D2E9", 
        "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
        "revision_end": null, 
        "revision_start": "2021-06-01T20:48:06.611020+00:00", 
        "started_at": "2021-06-01T20:48:06.610981+00:00", 
        "type": "generic", 
        "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
      }

The *id*, *user_id* and *project_id* attributes must be UUID. The timestamp
describing the lifespan of the resource are optional, and *started_at* is by
default set to the current timestamp.

It's possible to retrieve the resource by the URL provided in the `Location`
header.

More specialized resources can be created. For example, the *instance* is used
to describe an OpenStack instance as managed by Nova_.


   .. sourcecode:: http

      POST /v1/resource/instance HTTP/1.1
      Content-Type: application/json
      Content-Length: 351

      {
        "display_name": "myvm", 
        "ended_at": "2014-01-04 10:00:12", 
        "flavor_id": "2", 
        "host": "compute1", 
        "id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
        "image_ref": "http://image", 
        "metrics": {}, 
        "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
        "started_at": "2014-01-02 23:23:34", 
        "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
      }

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Location: http://localhost/v1/resource/instance/6868da77-fa82-4e67-aba9-270c5ae8cbca
      ETag: "14f5e9a6f71553abe10e1fd493c78b0aede7f9e1"
      Last-Modified: Tue, 01 Jun 2021 20:48:06 GMT
      Content-Length: 650
      Content-Type: application/json; charset=UTF-8

      {
        "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
        "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
        "display_name": "myvm", 
        "ended_at": "2014-01-04T10:00:12+00:00", 
        "flavor_id": "2", 
        "host": "compute1", 
        "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
        "image_ref": "http://image", 
        "metrics": {}, 
        "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
        "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
        "revision_end": null, 
        "revision_start": "2021-06-01T20:48:06.785154+00:00", 
        "server_group": null, 
        "started_at": "2014-01-02T23:23:34+00:00", 
        "type": "instance", 
        "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
      }

All specialized types have their own optional and mandatory attributes,
but they all include attributes from the generic type as well.

It is possible to create metrics at the same time you create a resource to save
some requests:


   .. sourcecode:: http

      POST /v1/resource/generic HTTP/1.1
      Content-Type: application/json
      Content-Length: 221

      {
        "id": "AB68DA77-FA82-4E67-ABA9-270C5A98CBCB", 
        "metrics": {
          "temperature": {
            "archive_policy_name": "low"
          }
        }, 
        "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
        "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
      }

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Location: http://localhost/v1/resource/generic/ab68da77-fa82-4e67-aba9-270c5a98cbcb
      ETag: "33d1a17dc9800ad0e1cb04cee28fa6f24e41478c"
      Last-Modified: Tue, 01 Jun 2021 20:48:06 GMT
      Content-Length: 573
      Content-Type: application/json; charset=UTF-8

      {
        "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
        "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
        "ended_at": null, 
        "id": "ab68da77-fa82-4e67-aba9-270c5a98cbcb", 
        "metrics": {
          "temperature": "7fd0ffb8-ca79-4a96-9109-9cd926ecdf71"
        }, 
        "original_resource_id": "AB68DA77-FA82-4E67-ABA9-270C5A98CBCB", 
        "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
        "revision_end": null, 
        "revision_start": "2021-06-01T20:48:06.642057+00:00", 
        "started_at": "2021-06-01T20:48:06.642010+00:00", 
        "type": "generic", 
        "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
      }

To retrieve a resource by its URL provided by the `Location` header at creation
time:


   .. sourcecode:: http

      GET /v1/resource/generic/75c44741-cc60-4033-804e-2d3098c7d2e9 HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      ETag: "c93e52f65a4369d8b350ca23777f7f14066eb685"
      Last-Modified: Tue, 01 Jun 2021 20:48:06 GMT
      Content-Length: 520
      Content-Type: application/json; charset=UTF-8

      {
        "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
        "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
        "ended_at": null, 
        "id": "75c44741-cc60-4033-804e-2d3098c7d2e9", 
        "metrics": {}, 
        "original_resource_id": "75C44741-CC60-4033-804E-2D3098C7D2E9", 
        "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
        "revision_end": null, 
        "revision_start": "2021-06-01T20:48:06.611020+00:00", 
        "started_at": "2021-06-01T20:48:06.610981+00:00", 
        "type": "generic", 
        "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
      }

It's possible to modify a resource by re-uploading it partially with the
modified fields:


   .. sourcecode:: http

      PATCH /v1/resource/instance/6868da77-fa82-4e67-aba9-270c5ae8cbca HTTP/1.1
      Content-Type: application/json
      Content-Length: 20

      {
        "host": "compute2"
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      ETag: "14b4f827c4904e590d1895f9cf2c360314312fc0"
      Last-Modified: Tue, 01 Jun 2021 20:48:07 GMT
      Content-Length: 650
      Content-Type: application/json; charset=UTF-8

      {
        "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
        "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
        "display_name": "myvm", 
        "ended_at": "2014-01-04T10:00:12+00:00", 
        "flavor_id": "2", 
        "host": "compute2", 
        "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
        "image_ref": "http://image", 
        "metrics": {}, 
        "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
        "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
        "revision_end": null, 
        "revision_start": "2021-06-01T20:48:07.341371+00:00", 
        "server_group": null, 
        "started_at": "2014-01-02T23:23:34+00:00", 
        "type": "instance", 
        "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
      }

And to retrieve its modification history:


   .. sourcecode:: http

      GET /v1/resource/instance/6868da77-fa82-4e67-aba9-270c5ae8cbca/history HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 1334
      Content-Type: application/json; charset=UTF-8

      [
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute1", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": "2021-06-01T20:48:07.341371+00:00", 
          "revision_start": "2021-06-01T20:48:06.785154+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }, 
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute2", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:07.341371+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      ]

It is possible to delete a resource altogether:


   .. sourcecode:: http

      DELETE /v1/resource/generic/75c44741-cc60-4033-804e-2d3098c7d2e9 HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 204 No Content
      Content-Length: 0

      

It is also possible to delete a batch of resources based on attribute values, and
returns a number of deleted resources.

To delete resources based on ids:


   .. sourcecode:: http

      DELETE /v1/resource/generic HTTP/1.1
      Content-Type: application/json
      Content-Length: 172

      {
        "in": {
          "id": [
            "239d7f33-984e-5dee-8550-a4ed32a632f0", 
            "078aad64-2b7a-50ba-93d8-2fedd62b46e6", 
            "bdaaeec7-3307-52cd-90d4-bfb8c97eb45d"
          ]
        }
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 14
      Content-Type: application/json; charset=UTF-8

      {
        "deleted": 3
      }

or delete resources based on time:


   .. sourcecode:: http

      DELETE /v1/resource/generic HTTP/1.1
      Content-Type: application/json
      Content-Length: 62

      {
        ">=": {
          "started_at": "2021-06-01T20:48:08.780106+00:00"
        }
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 14
      Content-Type: application/json; charset=UTF-8

      {
        "deleted": 1
      }

.. IMPORTANT::

  When a resource is deleted, all its associated metrics are deleted at the
  same time.

  When a batch of resources are deleted, an attribute filter is required to
  avoid deletion of the entire database.


All resources can be listed, either by using the `generic` type that will list
all types of resources, or by filtering on their resource type:


   .. sourcecode:: http

      GET /v1/resource/generic HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 1636
      Content-Type: application/json; charset=UTF-8

      [
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "ended_at": null, 
          "id": "75c44741-cc60-4033-804e-2d3098c7d2e9", 
          "metrics": {}, 
          "original_resource_id": "75C44741-CC60-4033-804E-2D3098C7D2E9", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.611020+00:00", 
          "started_at": "2021-06-01T20:48:06.610981+00:00", 
          "type": "generic", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }, 
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "ended_at": null, 
          "id": "ab68da77-fa82-4e67-aba9-270c5a98cbcb", 
          "metrics": {
            "temperature": "7fd0ffb8-ca79-4a96-9109-9cd926ecdf71"
          }, 
          "original_resource_id": "AB68DA77-FA82-4E67-ABA9-270C5A98CBCB", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.642057+00:00", 
          "started_at": "2021-06-01T20:48:06.642010+00:00", 
          "type": "generic", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }, 
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.785154+00:00", 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      ]

No attributes specific to the resource type are retrieved when using the
`generic` endpoint. To retrieve the details, either list using the specific
resource type endpoint:


   .. sourcecode:: http

      GET /v1/resource/instance HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 652
      Content-Type: application/json; charset=UTF-8

      [
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute1", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.785154+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      ]

or using `details=true` in the query parameter:


   .. sourcecode:: http

      GET /v1/resource/generic?details=true HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 1749
      Content-Type: application/json; charset=UTF-8

      [
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "ended_at": null, 
          "id": "75c44741-cc60-4033-804e-2d3098c7d2e9", 
          "metrics": {}, 
          "original_resource_id": "75C44741-CC60-4033-804E-2D3098C7D2E9", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.611020+00:00", 
          "started_at": "2021-06-01T20:48:06.610981+00:00", 
          "type": "generic", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }, 
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "ended_at": null, 
          "id": "ab68da77-fa82-4e67-aba9-270c5a98cbcb", 
          "metrics": {
            "temperature": "7fd0ffb8-ca79-4a96-9109-9cd926ecdf71"
          }, 
          "original_resource_id": "AB68DA77-FA82-4E67-ABA9-270C5A98CBCB", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.642057+00:00", 
          "started_at": "2021-06-01T20:48:06.642010+00:00", 
          "type": "generic", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }, 
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute1", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.785154+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      ]

.. note::

  Similar to metric list, query results are limited to `max_limit` value set in
  the configuration file.

Returned results represent a single page of data and are ordered by resouces'
revision_start time and started_at values:


   .. sourcecode:: http

      GET /v1/resource/generic?limit=2&sort=id:asc HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 1061
      Content-Type: application/json; charset=UTF-8

      [
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.785154+00:00", 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }, 
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "ended_at": null, 
          "id": "75c44741-cc60-4033-804e-2d3098c7d2e9", 
          "metrics": {}, 
          "original_resource_id": "75C44741-CC60-4033-804E-2D3098C7D2E9", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.611020+00:00", 
          "started_at": "2021-06-01T20:48:06.610981+00:00", 
          "type": "generic", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      ]

Each resource can be linked to any number of metrics. The `metrics` attributes
is a key/value field where the key is the name of the relationship and
the value is a metric:


   .. sourcecode:: http

      POST /v1/resource/instance HTTP/1.1
      Content-Type: application/json
      Content-Length: 368

      {
        "display_name": "myvm2", 
        "flavor_id": "2", 
        "host": "compute1", 
        "id": "6F24EDD9-5A2F-4592-B708-FFBED821C5D2", 
        "image_ref": "http://image", 
        "metrics": {
          "cpu.util": "bc3b6971-7cb8-4019-a36d-850f3f954ebb"
        }, 
        "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
        "server_group": "my_autoscaling_group", 
        "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
      }

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Location: http://localhost/v1/resource/instance/6f24edd9-5a2f-4592-b708-ffbed821c5d2
      ETag: "23f0aa069ca086961a7a10246a93606520089c56"
      Last-Modified: Tue, 01 Jun 2021 20:48:08 GMT
      Content-Length: 703
      Content-Type: application/json; charset=UTF-8

      {
        "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
        "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
        "display_name": "myvm2", 
        "ended_at": null, 
        "flavor_id": "2", 
        "host": "compute1", 
        "id": "6f24edd9-5a2f-4592-b708-ffbed821c5d2", 
        "image_ref": "http://image", 
        "metrics": {
          "cpu.util": "bc3b6971-7cb8-4019-a36d-850f3f954ebb"
        }, 
        "original_resource_id": "6F24EDD9-5A2F-4592-B708-FFBED821C5D2", 
        "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
        "revision_end": null, 
        "revision_start": "2021-06-01T20:48:08.226226+00:00", 
        "server_group": "my_autoscaling_group", 
        "started_at": "2021-06-01T20:48:08.226187+00:00", 
        "type": "instance", 
        "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
      }

It's also possible to create metrics dynamically while creating a resource:


   .. sourcecode:: http

      POST /v1/resource/instance HTTP/1.1
      Content-Type: application/json
      Content-Length: 362

      {
        "display_name": "myvm3", 
        "flavor_id": "2", 
        "host": "compute2", 
        "id": "15e9c872-7ca9-11e4-a2da-2fb4032dfc09", 
        "image_ref": "http://image", 
        "metrics": {
          "cpu.util": {
            "archive_policy_name": "short"
          }
        }, 
        "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
        "server_group": "my_autoscaling_group", 
        "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
      }

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Location: http://localhost/v1/resource/instance/15e9c872-7ca9-11e4-a2da-2fb4032dfc09
      ETag: "409743d8ddda7f4589493da4dad472675140cbc0"
      Last-Modified: Tue, 01 Jun 2021 20:48:08 GMT
      Content-Length: 703
      Content-Type: application/json; charset=UTF-8

      {
        "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
        "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
        "display_name": "myvm3", 
        "ended_at": null, 
        "flavor_id": "2", 
        "host": "compute2", 
        "id": "15e9c872-7ca9-11e4-a2da-2fb4032dfc09", 
        "image_ref": "http://image", 
        "metrics": {
          "cpu.util": "5c3ef93e-c360-4360-baf1-351a63074329"
        }, 
        "original_resource_id": "15e9c872-7ca9-11e4-a2da-2fb4032dfc09", 
        "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
        "revision_end": null, 
        "revision_start": "2021-06-01T20:48:08.266139+00:00", 
        "server_group": "my_autoscaling_group", 
        "started_at": "2021-06-01T20:48:08.266101+00:00", 
        "type": "instance", 
        "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
      }

The metric associated with a resource can be accessed and manipulated using the
usual `/v1/metric` endpoint or using the named relationship with the resource:


   .. sourcecode:: http

      GET /v1/resource/generic/6f24edd9-5a2f-4592-b708-ffbed821c5d2/metric/cpu.util/measures?start=2014-10-06T14:34 HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 185
      Content-Type: application/json; charset=UTF-8

      [
        [
          "2014-10-06T14:00:00+00:00", 
          3600.0, 
          24.7
        ], 
        [
          "2014-10-06T14:34:00+00:00", 
          60.0, 
          15.5
        ], 
        [
          "2014-10-06T14:34:12+00:00", 
          1.0, 
          6.0
        ], 
        [
          "2014-10-06T14:34:20+00:00", 
          1.0, 
          25.0
        ]
      ]

The same endpoint can be used to append metrics to a resource:


   .. sourcecode:: http

      POST /v1/resource/generic/6f24edd9-5a2f-4592-b708-ffbed821c5d2/metric HTTP/1.1
      Content-Type: application/json
      Content-Length: 42

      {
        "memory": {
          "archive_policy_name": "low"
        }
      }

   .. sourcecode:: http

      HTTP/1.1 204 No Content
      Content-Length: 0

      

.. _Nova: http://launchpad.net/nova

Resource Types
==============

Gnocchi is able to manage resource types with custom attributes.

To create a new resource type:


   .. sourcecode:: http

      POST /v1/resource_type HTTP/1.1
      Content-Type: application/json
      Content-Length: 360

      {
        "attributes": {
          "display_name": {
            "required": true, 
            "type": "string"
          }, 
          "enabled": {
            "required": false, 
            "type": "bool"
          }, 
          "myid": {
            "type": "uuid"
          }, 
          "prefix": {
            "max_length": 8, 
            "min_length": 3, 
            "required": false, 
            "type": "string"
          }, 
          "size": {
            "max": 32.8, 
            "min": 5, 
            "type": "number"
          }
        }, 
        "name": "my_custom_type"
      }

   .. sourcecode:: http

      HTTP/1.1 201 Created
      Location: http://localhost/v1/resource_type/my_custom_type
      Content-Length: 395
      Content-Type: application/json; charset=UTF-8

      {
        "attributes": {
          "display_name": {
            "max_length": 255, 
            "min_length": 0, 
            "required": true, 
            "type": "string"
          }, 
          "enabled": {
            "required": false, 
            "type": "bool"
          }, 
          "myid": {
            "required": true, 
            "type": "uuid"
          }, 
          "prefix": {
            "max_length": 8, 
            "min_length": 3, 
            "required": false, 
            "type": "string"
          }, 
          "size": {
            "max": 32.8, 
            "min": 5, 
            "required": true, 
            "type": "number"
          }
        }, 
        "name": "my_custom_type", 
        "state": "active"
      }

Then to retrieve its description:


   .. sourcecode:: http

      GET /v1/resource_type/my_custom_type HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 395
      Content-Type: application/json; charset=UTF-8

      {
        "attributes": {
          "display_name": {
            "max_length": 255, 
            "min_length": 0, 
            "required": true, 
            "type": "string"
          }, 
          "enabled": {
            "required": false, 
            "type": "bool"
          }, 
          "myid": {
            "required": true, 
            "type": "uuid"
          }, 
          "prefix": {
            "max_length": 8, 
            "min_length": 3, 
            "required": false, 
            "type": "string"
          }, 
          "size": {
            "max": 32.8, 
            "min": 5, 
            "required": true, 
            "type": "number"
          }
        }, 
        "name": "my_custom_type", 
        "state": "active"
      }

All resource types can be listed like this:


   .. sourcecode:: http

      GET /v1/resource_type HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 1013
      Content-Type: application/json; charset=UTF-8

      [
        {
          "attributes": {}, 
          "name": "generic", 
          "state": "active"
        }, 
        {
          "attributes": {
            "display_name": {
              "max_length": 255, 
              "min_length": 0, 
              "required": true, 
              "type": "string"
            }, 
            "flavor_id": {
              "max_length": 255, 
              "min_length": 0, 
              "required": true, 
              "type": "string"
            }, 
            "host": {
              "max_length": 255, 
              "min_length": 0, 
              "required": true, 
              "type": "string"
            }, 
            "image_ref": {
              "max_length": 255, 
              "min_length": 0, 
              "required": true, 
              "type": "string"
            }, 
            "server_group": {
              "max_length": 255, 
              "min_length": 0, 
              "required": false, 
              "type": "string"
            }
          }, 
          "name": "instance", 
          "state": "active"
        }, 
        {
          "attributes": {
            "display_name": {
              "max_length": 255, 
              "min_length": 0, 
              "required": true, 
              "type": "string"
            }, 
            "enabled": {
              "required": false, 
              "type": "bool"
            }, 
            "myid": {
              "required": true, 
              "type": "uuid"
            }, 
            "prefix": {
              "max_length": 8, 
              "min_length": 3, 
              "required": false, 
              "type": "string"
            }, 
            "size": {
              "max": 32.8, 
              "min": 5, 
              "required": true, 
              "type": "number"
            }
          }, 
          "name": "my_custom_type", 
          "state": "active"
        }, 
        {
          "attributes": {}, 
          "name": "my_other_type", 
          "state": "active"
        }
      ]

It can also be deleted if no more resources are associated to it:


   .. sourcecode:: http

      DELETE /v1/resource_type/my_custom_type HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 204 No Content
      Content-Length: 0

      

Attributes can be added or removed:


   .. sourcecode:: http

      PATCH /v1/resource_type/my_custom_type HTTP/1.1
      Content-Type: application/json-patch+json
      Content-Length: 211

      [
          {
              "op": "add",
              "path": "/attributes/awesome-stuff",
              "value": {"type": "bool", "required": false}
           },
           {
              "op": "remove",
              "path": "/attributes/prefix"
           }
      ]

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 366
      Content-Type: application/json; charset=UTF-8

      {
        "attributes": {
          "awesome-stuff": {
            "required": false, 
            "type": "bool"
          }, 
          "display_name": {
            "max_length": 255, 
            "min_length": 0, 
            "required": true, 
            "type": "string"
          }, 
          "enabled": {
            "required": false, 
            "type": "bool"
          }, 
          "myid": {
            "required": true, 
            "type": "uuid"
          }, 
          "size": {
            "max": 32.8, 
            "min": 5, 
            "required": true, 
            "type": "number"
          }
        }, 
        "name": "my_custom_type", 
        "state": "active"
      }

Creating resource type means creation of new tables on the indexer backend.
This is heavy operation that will lock some tables for a short amount of times.
When the resource type is created, its initial `state` is `creating`. When the
new tables have been created, the state switches to `active` and the new
resource type is ready to be used. If something unexpected occurs during this
step, the state switches to `creation_error`.

The same behavior occurs when the resource type is deleted. The state starts to
switch to `deleting`, the resource type is no more usable. Then the tables are
removed and the finally the resource_type is really deleted from the database.
If some unexpected occurs the state switches to `deletion_error`.

Searching for resources
=======================

It's possible to search for resources using a query mechanism, using the
`POST` method and uploading a JSON formatted query.

When listing resources, it is possible to filter resources based on attributes
values:


   .. sourcecode:: http

      POST /v1/search/resource/instance HTTP/1.1
      Content-Type: application/json
      Content-Length: 58

      {
        "=": {
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 652
      Content-Type: application/json; charset=UTF-8

      [
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute1", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.785154+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      ]

Or even:


   .. sourcecode:: http

      POST /v1/search/resource/instance HTTP/1.1
      Content-Type: application/json
      Content-Length: 30

      {
        "like": {
          "host": "compute%"
        }
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 652
      Content-Type: application/json; charset=UTF-8

      [
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute1", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.785154+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      ]

Complex operators such as `and` and `or` are also available:


   .. sourcecode:: http

      POST /v1/search/resource/instance HTTP/1.1
      Content-Type: application/json
      Content-Length: 113

      {
        "and": [
          {
            "=": {
              "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
            }
          }, 
          {
            ">=": {
              "started_at": "2010-01-01"
            }
          }
        ]
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 652
      Content-Type: application/json; charset=UTF-8

      [
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute1", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.785154+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      ]

Details about the resource can also be retrieved at the same time:


   .. sourcecode:: http

      POST /v1/search/resource/generic?details=true HTTP/1.1
      Content-Type: application/json
      Content-Length: 58

      {
        "=": {
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 1749
      Content-Type: application/json; charset=UTF-8

      [
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "ended_at": null, 
          "id": "75c44741-cc60-4033-804e-2d3098c7d2e9", 
          "metrics": {}, 
          "original_resource_id": "75C44741-CC60-4033-804E-2D3098C7D2E9", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.611020+00:00", 
          "started_at": "2021-06-01T20:48:06.610981+00:00", 
          "type": "generic", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }, 
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "ended_at": null, 
          "id": "ab68da77-fa82-4e67-aba9-270c5a98cbcb", 
          "metrics": {
            "temperature": "7fd0ffb8-ca79-4a96-9109-9cd926ecdf71"
          }, 
          "original_resource_id": "AB68DA77-FA82-4E67-ABA9-270C5A98CBCB", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.642057+00:00", 
          "started_at": "2021-06-01T20:48:06.642010+00:00", 
          "type": "generic", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }, 
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute1", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.785154+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      ]

It's possible to search for old revisions of resources in the same ways:


   .. sourcecode:: http

      POST /v1/search/resource/instance?history=true HTTP/1.1
      Content-Type: application/json
      Content-Length: 53

      {
        "=": {
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca"
        }
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 1334
      Content-Type: application/json; charset=UTF-8

      [
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute1", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": "2021-06-01T20:48:07.341371+00:00", 
          "revision_start": "2021-06-01T20:48:06.785154+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }, 
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute2", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:07.341371+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      ]

It is also possible to send the *history* parameter in the *Accept* header:


   .. sourcecode:: http

      POST /v1/search/resource/instance HTTP/1.1
      Content-Length: 53
      Content-Type: application/json
      Accept: application/json; history=true

      {
        "=": {
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca"
        }
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 1334
      Content-Type: application/json; charset=UTF-8

      [
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute1", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": "2021-06-01T20:48:07.341371+00:00", 
          "revision_start": "2021-06-01T20:48:06.785154+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }, 
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute2", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:07.341371+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      ]

The timerange of the history can be set, too:


   .. sourcecode:: http

      POST /v1/search/resource/instance HTTP/1.1
      Content-Length: 227
      Content-Type: application/json
      Accept: application/json; history=true

      {
        "and": [
          {
            "=": {
              "host": "compute1"
            }
          }, 
          {
            ">=": {
              "revision_start": "2021-06-01T20:48:06.785154+00:00"
            }
          }, 
          {
            "or": [
              {
                "<=": {
                  "revision_end": "2021-06-01T20:48:07.341371+00:00"
                }
              }, 
              {
                "=": {
                  "revision_end": null
                }
              }
            ]
          }
        ]
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 1318
      Content-Type: application/json; charset=UTF-8

      [
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute1", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": "2021-06-01T20:48:07.341371+00:00", 
          "revision_start": "2021-06-01T20:48:06.785154+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }, 
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": null, 
          "flavor_id": "2", 
          "host": "compute1", 
          "id": "ab0b5802-e79b-4c84-8998-9237f60d9cae", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "AB0B5802-E79B-4C84-8998-9237F60D9CAE", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:07.285897+00:00", 
          "server_group": null, 
          "started_at": "2021-06-01T20:48:07.285865+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      ]

The supported operators are: equal to (`=`, `==` or `eq`), less than (`<` or
`lt`), greater than (`>` or `gt`), less than or equal to (`<=`, `le` or `≤`)
greater than or equal to (`>=`, `ge` or `≥`) not equal to (`!=`, `ne` or `≠`),
value is in (`in`), value is like (`like`), or (`or` or `∨`), and (`and` or
`∧`) and negation (`not`).

The special attribute `lifespan` which is equivalent to `ended_at - started_at`
is also available in the filtering queries.


   .. sourcecode:: http

      POST /v1/search/resource/instance HTTP/1.1
      Content-Type: application/json
      Content-Length: 30

      {
        ">=": {
          "lifespan": "30 min"
        }
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 652
      Content-Type: application/json; charset=UTF-8

      [
        {
          "created_by_project_id": "2e5c8e44-3b6c-42ee-bd51-d346243ff7ce", 
          "created_by_user_id": "7c753baa-8907-4416-92a0-6110c9358b34", 
          "display_name": "myvm", 
          "ended_at": "2014-01-04T10:00:12+00:00", 
          "flavor_id": "2", 
          "host": "compute1", 
          "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca", 
          "image_ref": "http://image", 
          "metrics": {}, 
          "original_resource_id": "6868DA77-FA82-4E67-ABA9-270C5AE8CBCA", 
          "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D", 
          "revision_end": null, 
          "revision_start": "2021-06-01T20:48:06.785154+00:00", 
          "server_group": null, 
          "started_at": "2014-01-02T23:23:34+00:00", 
          "type": "instance", 
          "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
        }
      ]


Searching for values in metrics
===============================

It's possible to search for values in metrics. For example, this will look for
all values that are greater than or equal to 50 if we add 23 to them and that
are not equal to 55. You have to specify the list of metrics to look into by
using the `metric_id` query parameter several times.


   .. sourcecode:: http

      POST /v1/search/metric?metric_id=bc3b6971-7cb8-4019-a36d-850f3f954ebb HTTP/1.1
      Content-Type: application/json
      Content-Length: 46

      {
        "and": [
          {
            ">=": [
              {
                "+": 23
              }, 
              50
            ]
          }, 
          {
            "!=": 55
          }
        ]
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 155
      Content-Type: application/json; charset=UTF-8

      {
        "bc3b6971-7cb8-4019-a36d-850f3f954ebb": [
          [
            "2014-10-06T14:33:00+00:00", 
            60.0, 
            43.1
          ], 
          [
            "2014-10-06T14:33:57+00:00", 
            1.0, 
            43.1
          ]
        ]
      }

You can specify a time range to look for by specifying the `start` and/or
`stop` query parameter, and the aggregation method to use by specifying the
`aggregation` query parameter.

The supported operators are: equal to (`=`, `==` or `eq`), lesser than (`<` or
`lt`), greater than (`>` or `gt`), less than or equal to (`<=`, `le` or `≤`)
greater than or equal to (`>=`, `ge` or `≥`) not equal to (`!=`, `ne` or `≠`),
addition (`+` or `add`), substraction (`-` or `sub`), multiplication (`*`,
`mul` or `×`), division (`/`, `div` or `÷`). These operations take either one
argument, and in this case the second argument passed is the value, or it.

The operators or (`or` or `∨`), and (`and` or `∧`) and `not` are also
supported, and take a list of arguments as parameters.

Aggregation across metrics
==========================

Gnocchi allows to do on-the-fly aggregation of already aggregated data of
metrics.

It can also be done by providing the list of metrics to aggregate:


   .. sourcecode:: http

      GET /v1/aggregation/metric?metric=bc3b6971-7cb8-4019-a36d-850f3f954ebb&metric=5c3ef93e-c360-4360-baf1-351a63074329&start=2014-10-06T14:34&aggregation=mean HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 85
      Content-Type: application/json; charset=UTF-8

      [
        [
          "2014-10-06T14:34:12+00:00", 
          1.0, 
          12.25
        ], 
        [
          "2014-10-06T14:34:20+00:00", 
          1.0, 
          11.6
        ]
      ]

.. Note::

   This aggregation is done against the aggregates built and updated for
   a metric when new measurements are posted in Gnocchi. Therefore, the aggregate
   of this already aggregated data may not have sense for certain kind of
   aggregation method (e.g. stdev).

By default, the measures are aggregated using the aggregation method provided,
e.g. you'll get a mean of means, or a max of maxs. You can specify what method
to use over the retrieved aggregation by using the `reaggregation` parameter:


   .. sourcecode:: http

      GET /v1/aggregation/metric?metric=bc3b6971-7cb8-4019-a36d-850f3f954ebb&metric=5c3ef93e-c360-4360-baf1-351a63074329&aggregation=mean&reaggregation=min HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 123
      Content-Type: application/json; charset=UTF-8

      [
        [
          "2014-10-06T14:33:57+00:00", 
          1.0, 
          3.5
        ], 
        [
          "2014-10-06T14:34:12+00:00", 
          1.0, 
          4.5
        ], 
        [
          "2014-10-06T14:34:20+00:00", 
          1.0, 
          9.0
        ]
      ]

It's also possible to do that aggregation on metrics linked to resources. In
order to select these resources, the following endpoint accepts a query such as
the one described in `Searching for resources`_.


   .. sourcecode:: http

      POST /v1/aggregation/resource/instance/metric/cpu.util?start=2014-10-06T14:34&aggregation=mean HTTP/1.1
      Content-Type: application/json
      Content-Length: 47

      {
        "=": {
          "server_group": "my_autoscaling_group"
        }
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 85
      Content-Type: application/json; charset=UTF-8

      [
        [
          "2014-10-06T14:34:12+00:00", 
          1.0, 
          12.25
        ], 
        [
          "2014-10-06T14:34:20+00:00", 
          1.0, 
          11.6
        ]
      ]

It is possible to group the resource search results by any attribute of the
requested resource type, and the compute the aggregation:


   .. sourcecode:: http

      POST /v1/aggregation/resource/instance/metric/cpu.util?groupby=host&groupby=flavor_id HTTP/1.1
      Content-Type: application/json
      Content-Length: 47

      {
        "=": {
          "server_group": "my_autoscaling_group"
        }
      }

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 596
      Content-Type: application/json; charset=UTF-8

      [
        {
          "group": {
            "flavor_id": "2", 
            "host": "compute1"
          }, 
          "measures": [
            [
              "2014-10-06T14:00:00+00:00", 
              3600.0, 
              10.833333333333334
            ], 
            [
              "2014-10-06T14:33:00+00:00", 
              60.0, 
              3.5
            ], 
            [
              "2014-10-06T14:34:00+00:00", 
              60.0, 
              14.5
            ], 
            [
              "2014-10-06T14:33:57+00:00", 
              1.0, 
              3.5
            ], 
            [
              "2014-10-06T14:34:12+00:00", 
              1.0, 
              20.0
            ], 
            [
              "2014-10-06T14:34:20+00:00", 
              1.0, 
              9.0
            ]
          ]
        }, 
        {
          "group": {
            "flavor_id": "2", 
            "host": "compute2"
          }, 
          "measures": [
            [
              "2014-10-06T14:30:00+00:00", 
              1800.0, 
              14.6
            ], 
            [
              "2014-10-06T14:33:57+00:00", 
              1.0, 
              25.1
            ], 
            [
              "2014-10-06T14:34:12+00:00", 
              1.0, 
              4.5
            ], 
            [
              "2014-10-06T14:34:20+00:00", 
              1.0, 
              14.2
            ]
          ]
        }
      ]

Similar to retrieving measures for a single metric, the `refresh` parameter
can be provided to force all POSTed measures to be processed across all
metrics before computing the result.

Also aggregation across metrics have different behavior depending
on if boundary are set ('start' and 'stop') and if 'needed_overlap' is set.

If boundaries are not set, Gnocchi makes the aggregation only with points
at timestamp present in all timeseries.

But when boundaries are set, Gnocchi expects that we have certain
percent of timestamps common between timeseries, this percent is controlled
by needed_overlap (defaulted with 100%). If this percent is not reached an
error is returned.

Capabilities
============

The list aggregation methods that can be used in Gnocchi are extendable and
can differ between deployments. It is possible to get the supported list of
aggregation methods from the API server:


   .. sourcecode:: http

      GET /v1/capabilities HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 1030
      Content-Type: application/json; charset=UTF-8

      {
        "aggregation_methods": [
          "31pct", 
          "67pct", 
          "81pct", 
          "13pct", 
          "25pct", 
          "40pct", 
          "50pct", 
          "6pct", 
          "11pct", 
          "22pct", 
          "1pct", 
          "42pct", 
          "76pct", 
          "70pct", 
          "84pct", 
          "94pct", 
          "20pct", 
          "32pct", 
          "60pct", 
          "34pct", 
          "66pct", 
          "95pct", 
          "33pct", 
          "73pct", 
          "85pct", 
          "21pct", 
          "82pct", 
          "12pct", 
          "std", 
          "72pct", 
          "47pct", 
          "10pct", 
          "23pct", 
          "35pct", 
          "43pct", 
          "17pct", 
          "37pct", 
          "88pct", 
          "61pct", 
          "63pct", 
          "79pct", 
          "87pct", 
          "15pct", 
          "count", 
          "99pct", 
          "last", 
          "86pct", 
          "median", 
          "64pct", 
          "69pct", 
          "78pct", 
          "58pct", 
          "56pct", 
          "3pct", 
          "19pct", 
          "5pct", 
          "38pct", 
          "mean", 
          "57pct", 
          "59pct", 
          "65pct", 
          "39pct", 
          "16pct", 
          "36pct", 
          "89pct", 
          "93pct", 
          "48pct", 
          "28pct", 
          "75pct", 
          "98pct", 
          "18pct", 
          "52pct", 
          "7pct", 
          "9pct", 
          "min", 
          "55pct", 
          "90pct", 
          "96pct", 
          "45pct", 
          "68pct", 
          "14pct", 
          "44pct", 
          "2pct", 
          "4pct", 
          "92pct", 
          "26pct", 
          "max", 
          "49pct", 
          "53pct", 
          "29pct", 
          "74pct", 
          "80pct", 
          "24pct", 
          "51pct", 
          "62pct", 
          "97pct", 
          "54pct", 
          "77pct", 
          "41pct", 
          "71pct", 
          "46pct", 
          "83pct", 
          "8pct", 
          "30pct", 
          "91pct", 
          "first", 
          "sum", 
          "27pct"
        ], 
        "dynamic_aggregation_methods": [
          "moving-average"
        ]
      }

Status
======
The overall status of the Gnocchi installation can be retrieved via an API call
reporting values such as the number of new measures to process for each metric:


   .. sourcecode:: http

      GET /v1/status HTTP/1.1


      

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Length: 82
      Content-Type: application/json; charset=UTF-8

      {
        "storage": {
          "measures_to_process": {}, 
          "summary": {
            "measures": 0, 
            "metrics": 0
          }
        }
      }


Timestamp format
================

Timestamps used in Gnocchi are always returned using the ISO 8601 format.
Gnocchi is able to understand a few formats of timestamp when querying or
creating resources, for example

- "2014-01-01 12:12:34" or "2014-05-20T10:00:45.856219", ISO 8601 timestamps.
- "10 minutes", which means "10 minutes from now".
- "-2 days", which means "2 days ago".
- 1421767030, a Unix epoch based timestamp.