/api/query/gexp¶
Graphite is an excellent storage system for time series data with a number of built in functions to manipulate the data. To support transitions from Graphite to OpenTSDB, the /api/query/gexp endpoint supports URI queries similar but not identical to Graphite`s expressions. Graphite functions are generally formatted as func(<series>[, param1][, paramN]) with the ability to nest functions. TSD`s implementation follows the same pattern but uses an m style query (e.g. sum:proc.stat.cpu{host=foo,type=idle}) in place of the <series>. Nested functions are supported.
TSDB implements a subset of Graphite functions though we hope to add more in the future. For a list of Graphite functions and descriptions, see the Documentation. TSD supported functions appear below.
Note
Supported as of version 2.3
Verbs¶
GET
Requests¶
Queries can only be executed via GET using the URI at this time. (In the future, the /api/query/exp endpoint will support more flexibility.) This is an extension of the main /api/query endpoint so parameters in the request table are also supported here. Additional parameters include:
Name |
Data Type |
Required |
Description |
Example |
|---|---|---|---|---|
exp |
String |
Required |
The Graphite style expression to execute. The first parameter of a function must either be another function or a URI formatted Sub Query |
scale(sum:if.bytes_in{host=*},1024) |
Example Query String Requests¶
http://localhost:4242/api/query/gexp?start=1h-ago&exp=scale(sum:if.bytes_in{host=*},1024)
Response¶
The output is identical to /api/query.
Functions¶
Functions that accept a single metric query will operate across each time series result. E.g. if a query includes a group by on host such as scale(sum:if.bytes_in{host=*},1024), and multiple hosts exist with that metric, then a series for each host will be emitted and the function applied. For functions that take multiple metrics, a union is performed across each metric and the function is executed across each resulting series with matching tags. E.g with the query sum(sum:if.bytes_in{host=*},sum:if.bytes_out{host=*}), assume two hosts exist, web01 and web02. In this case, the output will be if.bytes_in{host=web01} + if.bytes_out{host=web01} and if.bytes_in{host=web02} + if.bytes_out{host=web02}. Missing series in any metric result set will be filled with the default fill value of the function.
Currently supported expressions include:
absolute(<metric>)¶
Emits the results as absolute values, converting negative values to positive.
diffSeries(<metric>[,<metricN>])¶
Returns the difference of all series in the list. Performs a UNION across tags in each metric result sets, defaulting to a fill value of zero. A maximum of 26 series are supported at this time.
divideSeries(<metric>[,<metricN>])¶
Returns the quotient of all series in the list. Performs a UNION across tags in each metric result sets, defaulting to a fill value of zero. A maximum of 26 series are supported at this time.
highestCurrent(<metric>,<n>)¶
Sorts all resulting time series by their most recent value and emits n number of series with the highest values. n must be a positive integer value.
highestMax(<metric>,<n>)¶
Sorts all resulting time series by the maximum value for the time span and emits n number of series with the highest values. n must be a positive integer value.
movingAverage(<metric>,<window>)¶
Emits a sliding window moving average for each data point and series in the metric. The window parameter may either be a positive integer that reflects the number of data points to maintain in the window (non-timed) or a time span specified by an integer followed by time unit such as `60s` or `60m` or `24h`. Timed windows must be in single quotes.
multiplySeries(<metric>[,<metricN>])¶
Returns the product of all series in the list. Performs a UNION across tags in each metric result sets, defaulting to a fill value of zero. A maximum of 26 series are supported at this time.
scale(<metric>,<factor>)¶
Multiplies each series by the factor where the factor can be a positive or negative floating point or integer value.
sumSeries(<metric>[,<metricN>])¶
Returns the sum of all series in the list. Performs a UNION across tags in each metric result sets, defaulting to a fill value of zero. A maximum of 26 series are supported at this time.