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.

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:

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

{
  "archive_policy_name": "high"
}
HTTP/1.1 201 Created
Location: http://localhost/v1/metric/882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b
Content-Length: 253
Content-Type: application/json; charset=UTF-8

{
  "archive_policy_name": "high",
  "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
  "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
  "id": "882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b",
  "name": null,
  "resource_id": null,
  "unit": null
}

Once created, you can retrieve the metric information:

GET /v1/metric/882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b HTTP/1.1
HTTP/1.1 200 OK
Content-Length: 598
Content-Type: application/json; charset=UTF-8

{
  "archive_policy": {
    "aggregation_methods": [
      "95pct",
      "min",
      "std",
      "mean",
      "median",
      "max",
      "count",
      "sum"
    ],
    "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": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
  "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
  "id": "882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b",
  "name": null,
  "resource": null,
  "unit": null
}

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

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

[
  {
    "archive_policy": {
      "aggregation_methods": [
        "95pct",
        "min",
        "std",
        "mean",
        "median",
        "max",
        "count",
        "sum"
      ],
      "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": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "id": "882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b",
    "name": null,
    "resource_id": null,
    "unit": null
  },
  {
    "archive_policy": {
      "aggregation_methods": [
        "95pct",
        "min",
        "std",
        "mean",
        "median",
        "max",
        "count",
        "sum"
      ],
      "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": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "id": "a8a1fd3e-a052-4acf-b405-8b6ad177b47c",
    "name": null,
    "resource_id": null,
    "unit": null
  }
]

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. Default ordering and limits as well as page start can be modified using query parameters:

GET /v1/metric?limit=100&sort=name:asc HTTP/1.1
HTTP/1.1 200 OK
Content-Length: 1203
Content-Type: application/json; charset=UTF-8

[
  {
    "archive_policy": {
      "aggregation_methods": [
        "95pct",
        "min",
        "std",
        "mean",
        "median",
        "max",
        "count",
        "sum"
      ],
      "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": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "id": "882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b",
    "name": null,
    "resource_id": null,
    "unit": null
  },
  {
    "archive_policy": {
      "aggregation_methods": [
        "95pct",
        "min",
        "std",
        "mean",
        "median",
        "max",
        "count",
        "sum"
      ],
      "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": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "id": "a8a1fd3e-a052-4acf-b405-8b6ad177b47c",
    "name": null,
    "resource_id": null,
    "unit": null
  }
]

It is possible to send measures to the metric:

POST /v1/metric/882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b/measures HTTP/1.1
Content-Length: 198
Content-Type: application/json

[
  {
    "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
  }
]
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:

GET /v1/metric/882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b/measures HTTP/1.1
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
  ]
]

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:

GET /v1/metric/882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b/measures?start=2014-10-06T14:34 HTTP/1.1
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:

GET /v1/metric/882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b/measures?aggregation=max HTTP/1.1
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:

GET /v1/metric/882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b/measures?granularity=1 HTTP/1.1
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:

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

{
  "882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b": [
    {
      "timestamp": "2014-10-06T14:34:12",
      "value": 12
    },
    {
      "timestamp": "2014-10-06T14:34:20",
      "value": 2
    }
  ],
  "a8a1fd3e-a052-4acf-b405-8b6ad177b47c": [
    {
      "timestamp": "2014-10-06T16:12:12",
      "value": 3
    },
    {
      "timestamp": "2014-10-06T18:14:52",
      "value": 4
    }
  ]
}
HTTP/1.1 202 Accepted
Content-Length: 0
Content-Type: text/html; charset=UTF-8

Or using named metrics of resources:

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

{
  "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
      }
    ]
  }
}
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:

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

{
  "back_window": 0,
  "definition": [
    {
      "granularity": "1s",
      "timespan": "1 hour"
    },
    {
      "points": 48,
      "timespan": "1 day"
    }
  ],
  "name": "short"
}
HTTP/1.1 201 Created
Location: http://localhost/v1/archive_policy/short
Content-Length: 279
Content-Type: application/json; charset=UTF-8

{
  "aggregation_methods": [
    "95pct",
    "min",
    "count",
    "mean",
    "median",
    "max",
    "std",
    "sum"
  ],
  "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.

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

{
  "aggregation_methods": [
    "-max",
    "-min"
  ],
  "back_window": 0,
  "definition": [
    {
      "granularity": "1s",
      "timespan": "1 hour"
    },
    {
      "points": 48,
      "timespan": "1 day"
    }
  ],
  "name": "short-without-max"
}
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": [
    "95pct",
    "count",
    "mean",
    "median",
    "std",
    "sum"
  ],
  "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:

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

{
  "aggregation_methods": [
    "95pct",
    "min",
    "std",
    "mean",
    "median",
    "max",
    "count",
    "sum"
  ],
  "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:

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

[
  {
    "aggregation_methods": [
      "95pct",
      "min",
      "std",
      "mean",
      "median",
      "max",
      "count",
      "sum"
    ],
    "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": [
      "95pct",
      "min",
      "std",
      "mean",
      "median",
      "max",
      "count",
      "sum"
    ],
    "back_window": 0,
    "definition": [
      {
        "granularity": "0:00:02",
        "points": 86400,
        "timespan": "2 days, 0:00:00"
      }
    ],
    "name": "no_granularity_match"
  },
  {
    "aggregation_methods": [
      "95pct",
      "min",
      "std",
      "mean",
      "median",
      "max",
      "count",
      "sum"
    ],
    "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": [
      "95pct",
      "min",
      "std",
      "mean",
      "median",
      "max",
      "count",
      "sum"
    ],
    "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": [
      "95pct",
      "min",
      "std",
      "mean",
      "median",
      "max",
      "count",
      "sum"
    ],
    "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": [
      "95pct",
      "count",
      "mean",
      "median",
      "std",
      "sum"
    ],
    "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:

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

{
  "definition": [
    {
      "granularity": "1s",
      "timespan": "1 hour"
    },
    {
      "points": 48,
      "timespan": "1 day"
    }
  ]
}
HTTP/1.1 200 OK
Content-Length: 279
Content-Type: application/json; charset=UTF-8

{
  "aggregation_methods": [
    "95pct",
    "min",
    "std",
    "mean",
    "median",
    "max",
    "count",
    "sum"
  ],
  "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:

DELETE /v1/archive_policy/some-archive-policy HTTP/1.1
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:

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

{
  "archive_policy_name": "low",
  "metric_pattern": "disk.io.*",
  "name": "test_rule"
}
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:

GET /v1/archive_policy_rule/test_rule HTTP/1.1
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:

GET /v1/archive_policy_rule HTTP/1.1
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:

DELETE /v1/archive_policy_rule/test_rule_delete HTTP/1.1
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:

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

{
  "id": "75C44741-CC60-4033-804E-2D3098C7D2E9",
  "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D",
  "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
}
HTTP/1.1 201 Created
Location: http://localhost/v1/resource/generic/75c44741-cc60-4033-804e-2d3098c7d2e9
ETag: "c609d8538a8d07daa56159754e8a3176adf11ea9"
Last-Modified: Wed, 29 Jun 2016 10:29:45 GMT
Content-Length: 520
Content-Type: application/json; charset=UTF-8

{
  "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
  "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
  "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": "2016-06-29T10:29:45.817579+00:00",
  "started_at": "2016-06-29T10:29:45.817557+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.

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

{
  "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"
}
HTTP/1.1 201 Created
Location: http://localhost/v1/resource/instance/6868da77-fa82-4e67-aba9-270c5ae8cbca
ETag: "457a94ea43445ea5ea948023515ff88fb3e0a751"
Last-Modified: Wed, 29 Jun 2016 10:29:45 GMT
Content-Length: 650
Content-Type: application/json; charset=UTF-8

{
  "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
  "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
  "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": "2016-06-29T10:29:45.932581+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:

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

{
  "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"
}
HTTP/1.1 201 Created
Location: http://localhost/v1/resource/generic/ab68da77-fa82-4e67-aba9-270c5a98cbcb
ETag: "993eb8959ef6dedc7f093f7c92af71dd54168530"
Last-Modified: Wed, 29 Jun 2016 10:29:45 GMT
Content-Length: 573
Content-Type: application/json; charset=UTF-8

{
  "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
  "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
  "ended_at": null,
  "id": "ab68da77-fa82-4e67-aba9-270c5a98cbcb",
  "metrics": {
    "temperature": "3928c828-6d39-4ac7-9fb5-99065f835bbc"
  },
  "original_resource_id": "AB68DA77-FA82-4E67-ABA9-270C5A98CBCB",
  "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D",
  "revision_end": null,
  "revision_start": "2016-06-29T10:29:45.846063+00:00",
  "started_at": "2016-06-29T10:29:45.846026+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:

GET /v1/resource/generic/75c44741-cc60-4033-804e-2d3098c7d2e9 HTTP/1.1
HTTP/1.1 200 OK
ETag: "c609d8538a8d07daa56159754e8a3176adf11ea9"
Last-Modified: Wed, 29 Jun 2016 10:29:45 GMT
Content-Length: 520
Content-Type: application/json; charset=UTF-8

{
  "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
  "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
  "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": "2016-06-29T10:29:45.817579+00:00",
  "started_at": "2016-06-29T10:29:45.817557+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:

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

{
  "host": "compute2"
}
HTTP/1.1 200 OK
ETag: "a6dfd9f8ac9d43e4c2507204ab8a08f10b24f005"
Last-Modified: Wed, 29 Jun 2016 10:29:46 GMT
Content-Length: 650
Content-Type: application/json; charset=UTF-8

{
  "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
  "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
  "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": "2016-06-29T10:29:46.284925+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:

GET /v1/resource/instance/6868da77-fa82-4e67-aba9-270c5ae8cbca/history HTTP/1.1
HTTP/1.1 200 OK
Content-Length: 1334
Content-Type: application/json; charset=UTF-8

[
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:46.284925+00:00",
    "revision_start": "2016-06-29T10:29:45.932581+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": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:46.284925+00:00",
    "server_group": null,
    "started_at": "2014-01-02T23:23:34+00:00",
    "type": "instance",
    "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
  }
]

It possible to delete a resource altogether:

DELETE /v1/resource/generic/75c44741-cc60-4033-804e-2d3098c7d2e9 HTTP/1.1
HTTP/1.1 204 No Content
Content-Length: 0

Important

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

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:

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

[
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:45.817579+00:00",
    "started_at": "2016-06-29T10:29:45.817557+00:00",
    "type": "generic",
    "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
  },
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "ended_at": null,
    "id": "ab68da77-fa82-4e67-aba9-270c5a98cbcb",
    "metrics": {
      "temperature": "3928c828-6d39-4ac7-9fb5-99065f835bbc"
    },
    "original_resource_id": "AB68DA77-FA82-4E67-ABA9-270C5A98CBCB",
    "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D",
    "revision_end": null,
    "revision_start": "2016-06-29T10:29:45.846063+00:00",
    "started_at": "2016-06-29T10:29:45.846026+00:00",
    "type": "generic",
    "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
  },
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:45.932581+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:

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

[
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:45.932581+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:

GET /v1/resource/generic?details=true HTTP/1.1
HTTP/1.1 200 OK
Content-Length: 1749
Content-Type: application/json; charset=UTF-8

[
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:45.817579+00:00",
    "started_at": "2016-06-29T10:29:45.817557+00:00",
    "type": "generic",
    "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
  },
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "ended_at": null,
    "id": "ab68da77-fa82-4e67-aba9-270c5a98cbcb",
    "metrics": {
      "temperature": "3928c828-6d39-4ac7-9fb5-99065f835bbc"
    },
    "original_resource_id": "AB68DA77-FA82-4E67-ABA9-270C5A98CBCB",
    "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D",
    "revision_end": null,
    "revision_start": "2016-06-29T10:29:45.846063+00:00",
    "started_at": "2016-06-29T10:29:45.846026+00:00",
    "type": "generic",
    "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
  },
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:45.932581+00:00",
    "server_group": null,
    "started_at": "2014-01-02T23:23:34+00:00",
    "type": "instance",
    "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
  }
]

Similar to metric list, query results are limited to max_limit value set in the configuration file. Returned results are ordered by resouces’ revision_start time and started_at values:

GET /v1/resource/generic?limit=2&sort=id:asc HTTP/1.1
HTTP/1.1 200 OK
Content-Length: 1061
Content-Type: application/json; charset=UTF-8

[
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:45.932581+00:00",
    "started_at": "2014-01-02T23:23:34+00:00",
    "type": "instance",
    "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
  },
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:45.817579+00:00",
    "started_at": "2016-06-29T10:29:45.817557+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:

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

{
  "display_name": "myvm2",
  "flavor_id": "2",
  "host": "compute1",
  "id": "6F24EDD9-5A2F-4592-B708-FFBED821C5D2",
  "image_ref": "http://image",
  "metrics": {
    "cpu.util": "882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b"
  },
  "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D",
  "server_group": "my_autoscaling_group",
  "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
}
HTTP/1.1 201 Created
Location: http://localhost/v1/resource/instance/6f24edd9-5a2f-4592-b708-ffbed821c5d2
ETag: "d8ec25c09dc5eff97b00c0471934620df93a26b1"
Last-Modified: Wed, 29 Jun 2016 10:29:46 GMT
Content-Length: 703
Content-Type: application/json; charset=UTF-8

{
  "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
  "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
  "display_name": "myvm2",
  "ended_at": null,
  "flavor_id": "2",
  "host": "compute1",
  "id": "6f24edd9-5a2f-4592-b708-ffbed821c5d2",
  "image_ref": "http://image",
  "metrics": {
    "cpu.util": "882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b"
  },
  "original_resource_id": "6F24EDD9-5A2F-4592-B708-FFBED821C5D2",
  "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D",
  "revision_end": null,
  "revision_start": "2016-06-29T10:29:46.615495+00:00",
  "server_group": "my_autoscaling_group",
  "started_at": "2016-06-29T10:29:46.615479+00:00",
  "type": "instance",
  "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
}

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

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

{
  "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"
}
HTTP/1.1 201 Created
Location: http://localhost/v1/resource/instance/15e9c872-7ca9-11e4-a2da-2fb4032dfc09
ETag: "6c47a3110a3bf6dad0432cf35f0df0a28a008fa7"
Last-Modified: Wed, 29 Jun 2016 10:29:46 GMT
Content-Length: 703
Content-Type: application/json; charset=UTF-8

{
  "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
  "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
  "display_name": "myvm3",
  "ended_at": null,
  "flavor_id": "2",
  "host": "compute2",
  "id": "15e9c872-7ca9-11e4-a2da-2fb4032dfc09",
  "image_ref": "http://image",
  "metrics": {
    "cpu.util": "28307313-252e-4ec4-bd60-f9d7cdb2a117"
  },
  "original_resource_id": "15e9c872-7ca9-11e4-a2da-2fb4032dfc09",
  "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D",
  "revision_end": null,
  "revision_start": "2016-06-29T10:29:46.640439+00:00",
  "server_group": "my_autoscaling_group",
  "started_at": "2016-06-29T10:29:46.640422+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:

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

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

{
  "memory": {
    "archive_policy_name": "low"
  }
}
HTTP/1.1 204 No Content
Content-Length: 0

Resource Types

Gnocchi is able to manage resource types with custom attributes.

To create a new resource type:

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

{
  "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"
}
HTTP/1.1 201 Created
Location: http://localhost/v1/resource_type/my_custom_type
Content-Length: 376
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"
}

Then to retrieve its description:

GET /v1/resource_type/my_custom_type HTTP/1.1
HTTP/1.1 200 OK
Content-Length: 376
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"
}

All resource types can be listed like this:

GET /v1/resource_type HTTP/1.1
HTTP/1.1 200 OK
Content-Length: 937
Content-Type: application/json; charset=UTF-8

[
  {
    "attributes": {},
    "name": "generic"
  },
  {
    "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"
  },
  {
    "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"
  },
  {
    "attributes": {},
    "name": "my_other_type"
  }
]

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

DELETE /v1/resource_type/my_custom_type HTTP/1.1
HTTP/1.1 204 No Content
Content-Length: 0

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:

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

{
  "=": {
    "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
  }
}
HTTP/1.1 200 OK
Content-Length: 652
Content-Type: application/json; charset=UTF-8

[
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:45.932581+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:

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

{
  "like": {
    "host": "compute%"
  }
}
HTTP/1.1 200 OK
Content-Length: 652
Content-Type: application/json; charset=UTF-8

[
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:45.932581+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:

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

{
  "and": [
    {
      "=": {
        "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
      }
    },
    {
      ">=": {
        "started_at": "2010-01-01"
      }
    }
  ]
}
HTTP/1.1 200 OK
Content-Length: 652
Content-Type: application/json; charset=UTF-8

[
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:45.932581+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:

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

{
  "=": {
    "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
  }
}
HTTP/1.1 200 OK
Content-Length: 1749
Content-Type: application/json; charset=UTF-8

[
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:45.817579+00:00",
    "started_at": "2016-06-29T10:29:45.817557+00:00",
    "type": "generic",
    "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
  },
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "ended_at": null,
    "id": "ab68da77-fa82-4e67-aba9-270c5a98cbcb",
    "metrics": {
      "temperature": "3928c828-6d39-4ac7-9fb5-99065f835bbc"
    },
    "original_resource_id": "AB68DA77-FA82-4E67-ABA9-270C5A98CBCB",
    "project_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D",
    "revision_end": null,
    "revision_start": "2016-06-29T10:29:45.846063+00:00",
    "started_at": "2016-06-29T10:29:45.846026+00:00",
    "type": "generic",
    "user_id": "BD3A1E52-1C62-44CB-BF04-660BD88CD74D"
  },
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:45.932581+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:

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

{
  "=": {
    "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca"
  }
}
HTTP/1.1 200 OK
Content-Length: 1334
Content-Type: application/json; charset=UTF-8

[
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:46.284925+00:00",
    "revision_start": "2016-06-29T10:29:45.932581+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": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:46.284925+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:

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

{
  "=": {
    "id": "6868da77-fa82-4e67-aba9-270c5ae8cbca"
  }
}
HTTP/1.1 200 OK
Content-Length: 1334
Content-Type: application/json; charset=UTF-8

[
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:46.284925+00:00",
    "revision_start": "2016-06-29T10:29:45.932581+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": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:46.284925+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:

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

{
  "and": [
    {
      "=": {
        "host": "compute1"
      }
    },
    {
      ">=": {
        "revision_start": "2016-06-29T10:29:45.932581+00:00"
      }
    },
    {
      "or": [
        {
          "<=": {
            "revision_end": "2016-06-29T10:29:46.284925+00:00"
          }
        },
        {
          "=": {
            "revision_end": null
          }
        }
      ]
    }
  ]
}
HTTP/1.1 200 OK
Content-Length: 1318
Content-Type: application/json; charset=UTF-8

[
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:46.284925+00:00",
    "revision_start": "2016-06-29T10:29:45.932581+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": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:46.253003+00:00",
    "server_group": null,
    "started_at": "2016-06-29T10:29:46.252990+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.

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

{
  ">=": {
    "lifespan": "30 min"
  }
}
HTTP/1.1 200 OK
Content-Length: 652
Content-Type: application/json; charset=UTF-8

[
  {
    "created_by_project_id": "757f8b42-1d94-4ccb-9ba9-45b4eebde4a2",
    "created_by_user_id": "edc33935-8538-4e97-a218-135b22a15638",
    "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": "2016-06-29T10:29:45.932581+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.

POST /v1/search/metric?metric_id=882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b HTTP/1.1
Content-Length: 46
Content-Type: application/json

{
  "and": [
    {
      ">=": [
        {
          "+": 23
        },
        50
      ]
    },
    {
      "!=": 55
    }
  ]
}
HTTP/1.1 200 OK
Content-Length: 155
Content-Type: application/json; charset=UTF-8

{
  "882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b": [
    [
      "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:

GET /v1/aggregation/metric?metric=882c5f4a-6c2f-4610-b9f6-fbf6bbb3898b&metric=28307313-252e-4ec4-bd60-f9d7cdb2a117&start=2014-10-06T14:34&aggregation=mean HTTP/1.1
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).

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.

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

{
  "=": {
    "server_group": "my_autoscaling_group"
  }
}
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:

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

{
  "=": {
    "server_group": "my_autoscaling_group"
  }
}
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
      ]
    ]
  }
]

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:

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

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

GET /v1/status HTTP/1.1
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.