/api/query/exp

This endpoint allows for querying data using expressions. The query is broken up into different sections.

Two set operations (or Joins) are allowed. The union of all time series ore the intersection.

For example we can compute “a + b” with a group by on the host field. Both metrics queried alone would emit a time series per host, e.g. maybe one for “web01”, “web02” and “web03”. Lets say metric “a” has values for all 3 hosts but metric “b” is missing “web03”.

With the intersection operator, the expression will effectively add “a.web01 + b.web01” and “a.web02 + b.web02” but will skip emitting anything for “web03”. Be aware of this if you see fewer outputs that you expected or you see errors about no series available after intersection.

With the union operator the expression will add the web01 and web02 series but for metric “b”, it will substitute the metric’s fill policy value for the results.

Note

Supported as of version 2.3

Verbs

  • POST

Requests

The various sections implemented include:

“time”

The time section is required and is a single JSON object. This affects the time range and optional reductions for all metrics requested.

Name

Data Type

Required

Description

Default

Example

start

Integer

Required

The start time for the query. This may be relative, absolute human readable or absolute Unix Epoch.

1h-ago, 2015/05/05-00:00:00

aggregator

String

Required

The global aggregation function to use for all metrics. It may be overridden on a per metric basis.

sum

end

Integer

Optional

The end time for the query. If left out, the end is now

now

1h-ago, 2015/05/05-00:00:00

downsampler

Object

Optional

Reduces the number of data points returned. The format is defined below

None

See below

rate

Boolean

Optional

Whether or not to calculate all metrics as rates, i.e. value per second. This is computed before expressions.

false

true

E.g.

  1. "time":{ "start":"1h-ago", "end":"10m-ago", "downsampler":{"interval":"15m","aggregator":"max"}

Downsampler

Name

Data Type

Required

Description

Default

Example

interval

String

Required

A downsampling interval, i.e. what time span to rollup raw values into. The format is <#><unit>, e.g. 15m

1h

aggregator

String

Required

The aggregation function to use for reducing the data points

avg

fillPolicy

Object

Optional

A policy to use for filling buckets that are missing data points

None

See Below

Fill Policies

These are used to replace “missing” values, i.e. when a data point was expected but couldn’t be found in storage.

Name

Data Type

Required

Description

Default

Example

policy

String

Required

The name of a policy to use. The values are listed in the table below

zero

value

Double

Optional

For scalar fills, an optional value that can be used during substitution

NaN

42

Name

Description

nan

Emits a NaN if all values in the aggregation function were NaN or “missing”. For aggregators, NaNs are treated as “sentinel” values that cause the function to skip over the values. Note that if a series emits a NaN in an expression, the NaN is infectious and will cause the output of that expression to be NaN. At serialization the NaN will be emitted.

null

Emits a Null at serialization time. During computation the values are treated as NaNs.

zero

Emits a zero when the value is missing

scalar

Emits a user defined value when a data point is missing. Must specify the value with value. The value can be an integer or floating point.

Note that if you try to supply a value that is incompatible with the type the query will throw an exception. E.g. supplying a value with the NaN that isn’t NaN will throw an error.

E.g.

  1. {"policy":"scalar","value":"1"}

“filters”

Filters are for selecting various time series based on the tag keys and values. At least one filter must be specified (for now) with at least an aggregation function supplied. Fields include:

Name

Data Type

Required

Description

Default

Example

id

String

Required

A unique ID for the filter. Cannot be the same as any metric or expression ID

f1

tags

Array

Optional

A list of filters on tag values

None

See below

E.g.

  1. "filters":[
  2.   "id":"f1",
  3.   "tags":[
  4.     {
  5.       "type":"wildcard",
  6.       "tagk":"host",
  7.       "filter":"*",
  8.       "groupBy":true
  9.     },
  10.     {
  11.       "type":"literal_or",
  12.       "tagk":"colo",
  13.       "filter":"lga",
  14.       "groupBy":false
  15.     }
  16.    ]
  17.   ]

Filter Fields

Within the “tags” field you can have one or more filter. The list of filters can be found via the /api/config/filters endpoint.

Name

Data Type

Required

Description

Default

Example

type

String

Required

The name of the filter from the API

regexp

tagk

String

Required

The tag key name such as host or colo that we filter on

host

filter

String

Required

The value to filter on. This depends on the filter in use. See the API for details

web.*mysite.com

groupBy

Boolean

Optional

Whether or not to group results by the tag values matching this filter. E.g. grouping by host will return one result per host. Not grouping by host would aggregate (using the aggregation function) all results for the metric into one series

false

true

“metrics”

The metrics list determines which metrics are included in the expression. There must be at least one metric.

Name

Data Type

Required

Description

Default

Example

id

String

Required

A unique ID for the metric. This MUST be a simple string, no punctuation or spaces

cpunice

filter

String

Required

The filter to use when fetching this metric. It must match a filter in the filters array

f1

metric

String

Required

The name of a metric in OpenTSDB

system.cpu.nice

aggregator

String

Optional

An optional aggregation function to overload the global function in time for just this metric

time’s aggregator

count

fillPolicy

Object

Optional

If downsampling is not used, this can be included to determine what to emit in calculations. It will also override the downsampling policy

zero fill

See above

E.g.

  1. {"id":"cpunice", "filter":"f1", "metric":"system.cpu.nice"}

“expressions”

A list of one or more expressions over the metrics. The variables in an expression MUST refer to either a metric ID field or an expression ID field. Nested expressions are supported but exceptions will be thrown if a self reference or circular dependency is detected. So far only basic operations are supported such as addition, subtraction, multiplication, division, modulo

Name

Data Type

Required

Description

Default

Example

id

String

Required

A unique ID for the expression

cpubusy

expr

String

Required

The expression to execute

a + b / 1024

join

Object

Optional

The set operation or “join” to perform for series across sets.

union

See below

fillPolicy

Object

Optional

An optional fill policy for the expression when it is used in a nested expression and doesn’t have a value

NaN

See above

E.g.

  1. {
  2.   "id": "cpubusy",
  3.   "expr": "(((a + b + c + d + e + f + g) - g) / (a + b + c + d + e + f + g)) * 100",
  4.   "join": {
  5.       "operator": "intersection",
  6.       "useQueryTags": true,
  7.       "includeAggTags": false
  8.   }
  9. }

Joins

The join object controls how the various time series for a given metric are merged within an expression. The two basic operations supported at this time are the union and intersection operators. Additional flags control join behavior.

Name

Data Type

Required

Description

Default

Example

operator

String

Required

The operator to use, either union or intersection

intersection

useQueryTags

Boolean

Optional

Whether or not to use just the tags explicitly defined in the filters when computing the join keys

false

true

includeAggTags

Boolean

Optional

Whether or not to include the tag keys that were aggregated out of a series in the join key

true

false

“outputs”

These determine the output behavior and allow you to eliminate some expressions from the results or include the raw metrics. By default, if this section is missing, all expressions and only the expressions will be serialized. The field is a list of one or more output objects. More fields will be added later with flags to affect the output.

Name

Data Type

Required

Description

Default

Example

id

String

Required

The ID of the metric or expression

e

alias

String

Optional

An optional descriptive name for series

System Busy

E.g.

  1. {"id":"e", "alias":"System Busy"}

Note

The id field for all objects can not contain spaces, special characters or periods at this time.

Complete Example

  1. {
  2.    "time": {
  3.        "start": "1y-ago",
  4.        "aggregator":"sum"
  5.    },
  6.    "filters": [
  7.        {
  8.            "tags": [
  9.                {
  10.                    "type": "wildcard",
  11.                    "tagk": "host",
  12.                    "filter": "web*",
  13.                    "groupBy": true
  14.                }
  15.            ],
  16.            "id": "f1"
  17.        }
  18.    ],
  19.    "metrics": [
  20.        {
  21.            "id": "a",
  22.            "metric": "sys.cpu.user",
  23.            "filter": "f1",
  24.            "fillPolicy":{"policy":"nan"}
  25.        },
  26.        {
  27.            "id": "b",
  28.            "metric": "sys.cpu.iowait",
  29.            "filter": "f1",
  30.            "fillPolicy":{"policy":"nan"}
  31.        }
  32.    ],
  33.    "expressions": [
  34.        {
  35.            "id": "e",
  36.            "expr": "a + b"
  37.        },
  38.        {
  39.          "id":"e2",
  40.          "expr": "e * 2"
  41.        },
  42.        {
  43.          "id":"e3",
  44.          "expr": "e2 * 2"
  45.        },
  46.        {
  47.          "id":"e4",
  48.          "expr": "e3 * 2"
  49.        },
  50.        {
  51.          "id":"e5",
  52.          "expr": "e4 + e2"
  53.        }
  54.     ],
  55.     "outputs":[
  56.       {"id":"e5", "alias":"Mega expression"},
  57.       {"id":"a", "alias":"CPU User"}
  58.     ]
  59.  }

Response

The output will contain a list of objects in the outputs array with the results in an array of arrays representing each time series followed by meta data for each series and the query overall. Also included is the original query and some summary statistics. The fields include:

Name

Description

id

The expression ID the output matches

dps

The array of results. Each sub array starts with the timestamp in ms as the first (offset 0) value. The remaining values are the results for each series when a group by was applied.

dpsMeta

Meta data around the query including the first and last timestamps, number of result “sets”, or sub arrays, and the number of series represented.

datapoints

The total number of data points returned to the user after aggregation

meta

Data about each time series in the result set. The fields are below

The meta section contains ordered information about each time series in the output arrays. The first element in the array will always have a metrics value of timestamp and no other data.

Name

Description

index

The index in the data point arrays that the meta refers to

metrics

The different metric names included in the expression

commonTags

Tag keys and values that were common across all time series that were aggregated in the resulting series

aggregatedTags

Tag keys that appeared in all series in the resulting series but had different values

dps

The number of data points emitted

rawDps

The number of raw values wrapped into the result

Example Responses

  1. {
  2.   "outputs": [
  3.       {
  4.           "id": "Mega expression",
  5.           "dps": [
  6.               [
  7.                   1431561600000,
  8.                   1010,
  9.                   1030
  10.               ],
  11.               [
  12.                   1431561660000,
  13.                   "NaN",
  14.                   "NaN"
  15.               ],
  16.               [
  17.                   1431561720000,
  18.                   "NaN",
  19.                   "NaN"
  20.               ],
  21.               [
  22.                   1431561780000,
  23.                   1120,
  24.                   1140
  25.               ]
  26.           ],
  27.           "dpsMeta": {
  28.               "firstTimestamp": 1431561600000,
  29.               "lastTimestamp": 1431561780000,
  30.               "setCount": 4,
  31.               "series": 2
  32.           },
  33.           "meta": [
  34.               {
  35.                   "index": 0,
  36.                   "metrics": [
  37.                       "timestamp"
  38.                   ]
  39.               },
  40.               {
  41.                   "index": 1,
  42.                   "metrics": [
  43.                       "sys.cpu",
  44.                       "sys.iowait"
  45.                   ],
  46.                   "commonTags": {
  47.                       "host": "web01"
  48.                   },
  49.                   "aggregatedTags": []
  50.               },
  51.               {
  52.                   "index": 2,
  53.                   "metrics": [
  54.                       "sys.cpu",
  55.                       "sys.iowait"
  56.                   ],
  57.                   "commonTags": {
  58.                       "host": "web02"
  59.                   },
  60.                   "aggregatedTags": []
  61.               }
  62.           ]
  63.       },
  64.       {
  65.           "id": "sys.cpu",
  66.           "dps": [
  67.               [
  68.                   1431561600000,
  69.                   1,
  70.                   2
  71.               ],
  72.               [
  73.                   1431561660000,
  74.                   3,
  75.                   0
  76.               ],
  77.               [
  78.                   1431561720000,
  79.                   5,
  80.                   0
  81.               ],
  82.               [
  83.                   1431561780000,
  84.                   7,
  85.                   8
  86.               ]
  87.           ],
  88.           "dpsMeta": {
  89.               "firstTimestamp": 1431561600000,
  90.               "lastTimestamp": 1431561780000,
  91.               "setCount": 4,
  92.               "series": 2
  93.           },
  94.           "meta": [
  95.               {
  96.                   "index": 0,
  97.                   "metrics": [
  98.                       "timestamp"
  99.                   ]
  100.               },
  101.               {
  102.                   "index": 1,
  103.                   "metrics": [
  104.                       "sys.cpu"
  105.                   ],
  106.                   "commonTags": {
  107.                       "host": "web01"
  108.                   },
  109.                   "aggregatedTags": []
  110.               },
  111.               {
  112.                   "index": 2,
  113.                   "metrics": [
  114.                       "sys.cpu"
  115.                   ],
  116.                   "commonTags": {
  117.                       "host": "web02"
  118.                   },
  119.                   "aggregatedTags": []
  120.               }
  121.           ]
  122.       }
  123.   ],
  124.   "statsSummary": {
  125.       "datapoints": 0,
  126.       "rawDatapoints": 0,
  127.       "aggregationTime": 0,
  128.       "serializationTime": 33,
  129.       "storageTime": 77,
  130.       "timeTotal": 148.63
  131.   },
  132.   "query": {
  133.       "name": null,
  134.       "time": {
  135.           "start": "1y-ago",
  136.           "end": null,
  137.           "timezone": null,
  138.           "downsampler": null,
  139.           "aggregator": "sum"
  140.       },
  141.       "filters": [
  142.           {
  143.               "id": "f1",
  144.               "tags": [
  145.                   {
  146.                       "tagk": "host",
  147.                       "filter": "web*",
  148.                       "group_by": true,
  149.                       "type": "wildcard"
  150.                   }
  151.               ]
  152.           }
  153.       ],
  154.       "metrics": [
  155.           {
  156.               "metric": "sys.cpu",
  157.               "id": "a",
  158.               "filter": "f1",
  159.               "aggregator": null,
  160.               "fillPolicy": {
  161.                   "policy": "nan",
  162.                   "value": "NaN"
  163.               },
  164.               "timeOffset": null
  165.           },
  166.           {
  167.               "metric": "sys.iowait",
  168.               "id": "b",
  169.               "filter": "f1",
  170.               "aggregator": null,
  171.               "fillPolicy": {
  172.                   "policy": "nan",
  173.                   "value": "NaN"
  174.               },
  175.               "timeOffset": null
  176.           }
  177.       ],
  178.       "expressions": [
  179.           {
  180.               "id": "e",
  181.               "expr": "a + b"
  182.           },
  183.           {
  184.               "id": "e2",
  185.               "expr": "e * 2"
  186.           },
  187.           {
  188.               "id": "e3",
  189.               "expr": "e2 * 2"
  190.           },
  191.           {
  192.               "id": "e4",
  193.               "expr": "e3 * 2"
  194.           },
  195.           {
  196.               "id": "e5",
  197.               "expr": "e4 + e2"
  198.           }
  199.       ],
  200.       "outputs": [
  201.           {
  202.               "id": "e5",
  203.               "alias": "Woot!"
  204.           },
  205.           {
  206.               "id": "a",
  207.               "alias": "Woot!2"
  208.           }
  209.       ]
  210.    }
  211. }