Jump to: navigation, search

Ceilometer/ComplexFilterExpressionsInAPIQueries

< Ceilometer
Revision as of 08:02, 14 December 2013 by Ildiko (talk | contribs) (Filter expression)

Architecture

The purpose of the improvement is to support rich query functionality in Ceilometer API. The current query support is limited, it's grammar cannot be extended easily.

REST Resources

The new solution includes new REST resources for provide complex queries for both the meter and alarm related data:

REST Resource Functionality Returned Object Type
'/query/meters' retrieve samples for meter(s) Sample
'/query/alarms' retrieve alarms Alarm
'/query/alarms/history' retrieve alarm history AlarmChange

As new resources were defined, the simple query support remained as it is now, which means that the API is backward compatible and also a new query grammar could be defined without limitations.

POST request

The new solution uses POST request, as the functionality of the query part of the GET request is very limited.

Expression Language

 filter := [] | expression
 expression := simple_expression | complex_expression
 simple_expression := [simple_operator, field_name, value]
 simple_operator := = | != | < | <= | > | >=
 complex_expression := [complex_operator, expression, expression]
 complex_operator := and | or

Where

  • field_name is the name of a field of the Sample, Alarm or AlarmChange object
    • currently directly mapped to db column name
  • value can be int, float, string, or iso date string for timestamp field

Orderby

List of field_name and sort instruction pairs:

orderby: ["field_name1", "ASC", "field_name2", "DESC", field_name3, "ASC", ...]

Limit

Number of rows returned, defined value should be int.

Supported DB drivers

  • SQLAlchmey
  • MongoDB

API example

Filter expression

Check for cpu_util samples reported between 18:00-18:15 or between 18:30 - 18:45 where the utilization is between 23 and 26 percent.

 cpu_util > 23% AND cpu_util < 26% AND ((timestamp < 2013-12-01T18:15:00 AND timestamp > 2013-12-01T18:00:00) OR (timestamp < 2013-12-02T18:45:00 AND timestamp > 2013-12-02T18:30:00))

Pretty printed json:

["and",
  ["and",
    ["and",
      ["=", "counter_name", "cpu_util"],
      [">", "counter_volume", 0.23]],
    ["and",
      ["=", "counter_name", "cpu_util"],
      ["<", "counter_volume", 0.26]]],
  ["or",
    ["and",
	  [">", "timestamp", "2013-12-01T18:00:00"],
	  ["<", "timestamp", "2013-12-01T18:15:00"]],
    ["and",
	  [">", "timestamp", "2013-12-01T18:30:00"],
	  ["<", "timestamp", "2013-12-01T18:45:00"]]]]

Filter expression in the POST request body:

{
"filter" : "[\"and\",[\"and\",[\"and\",[\"=\", \"counter_name\", \"cpu_util\"],[\">\", \"counter_volume\", 0.23]],[\"and\",[\"=\", \"counter_name\", \"cpu_util\"],[\"<\", \"counter_volume\", 0.26]]],[\"or\",[\"and\",[\">\", \"timestamp\", \"2013-12-01T18:00:00\"],[\"<\", \"timestamp\", \"2013-12-01T18:15:00\"]],[\"and\",[\">\", \"timestamp\", \"2013-12-01T18:30:00\"],[\"<\", \"timestamp\", \"2013-12-01T18:45:00\"]]]]"
}

Samples query

{
"filter" : "[\"and\",[\"and\",[\"and\",[\"=\", \"counter_name\", \"cpu_util\"],[\">\", \"counter_volume\", 0.23]],[\"and\",[\"=\", \"counter_name\", \"cpu_util\"],[\"<\", \"counter_volume\", 0.26]]],[\"or\",[\"and\",[\">\", \"timestamp\", \"2013-12-01T18:00:00\"],[\"<\", \"timestamp\", \"2013-12-01T18:15:00\"]],[\"and\",[\">\", \"timestamp\", \"2013-12-01T18:30:00\"],[\"<\", \"timestamp\", \"2013-12-01T18:45:00\"]]]]",
"orderby" : ["cpu_util", "ASC", "timestamp", "DESC"],
"limit" : 4
}