timeseries command is a starting command of DQL. It combines loading, filtering and aggregating metrics data into a time series output.
timeseries [column =] aggregation(metricKey [, default:] [, rollup:] [, rate:]) [, [column =] aggregation(metricKey, ...), ...] [, by:] [, filter:] [, interval: | bins:] [, from:] [, to:] [,timeframe:]
Example 11timeseries usage=avg(dt.host.cpu.usage)
Example 21timeseries min_cpu=min(dt.host.cpu.usage), max(dt.host.cpu.usage, default:99.9), by:dt.entity.host, filter:in(dt.entity.host, "HOST-1", "HOST-2"), interval:1h, from:-7d
timeseries command produces homogenous time series of aggregated data: all series have identical start and end timestamps, time interval and number of elements. The
timeframe column holds the start and end timestamps. The
interval column holds the time interval expressed as a
duration. Each aggregation (min, max, sum, avg) produces a column with the specified column name or a name derived from the aggregation expression. Each aggregation cell consists of the entire array of aggregated values for each timeslot defined by
Here is an example of the result of the
timeseries command. Note that:
- the first aggregation column name has been specified in the query (
- the second aggregation column name has not been specified in the query, hence the name is derived from the expression (
- the first aggregation does not specify a
defaultparameter, hence it can contain
nullfor empty time slots
- the second aggregation does specify a
defaultparameter, hence the empty time slots are replaced with the
99.9in this example)
Four aggregations are available: min, max, sum, and avg. It's possible to specify multiple aggregations in the same command. Aggregations can apply to different metric keys.
Default value for empty time slots
timeseries command produces homogenous time series of aggregated data: all series have identical start and end timestamps, time interval and number of elements. If data is missing for a particular time slot, it is filled with
null. Specifying a
default parameter fills empty time slots with the
default parameter value instead of
rate parameter divides the aggregated timeseries by the interval to normalize the timeseries to the selected specified duration. For instance, if
timeseries sum(dt.requests.failed) returns
[1,1,2,3] with a
5m interval, then
timeseries sum(dt.requests.failed, rate:1s) would return
timeseries command automatically calculates an appropriate time interval derived from the query timeframe. The timeframe is divided into time slots of identical time intervals, and data is then rolled up into each of these time slots so that the number of points per time series is suitable for graphing. For instance, to graph a metric over a 1-day timeframe, it is more manageable to use 10-minute interval data (144 points) than 1-minute interval data (1,440 points).
You can influence the calculated time interval by specifying either a custom
interval parameter or, via the
bins parameter, the desired number of time slots.
bins parameters are exclusive. Both parameters are optional.
If specified, the
bins parameter (range: 12–1,500) is used to calculate an equivalent time interval.
The resulting time interval, whether coming from the
interval parameter, is then adjusted so that:
The time interval matches a well-known interval (1 minute, 5 minutes, 10 minutes, 15 minutes, 30 minutes, or 1 hour)
The time interval does not exceed the maximum number of elements per series (1,500).
Data points are aggregated across time into time slots to deal with potentially large amounts of data. For instance, a day's data is combined into 10-minute time slots. This aggregation is called a rollup and happens in every timeseries query.
The aggregation function used to combine the data is dependent on the function used in the aggregation. For instance, assuming a metric with a
timeseries min(dt.host.cpu.usage) combines data into time slots using the
min function for each time slot and each host, and then aggregates using the
min function again across all hosts within each time slot, effectively performing a min of the min as expected.
rollupparameter can be used if it's necessary to specify a time aggregation function independently from the main aggregation, such as the average of the sums in the following example.1timeseries failed = avg(dt.requests.failed), rollup:sum
rollup parameter supports the following functions: