Metric commands
timeseries
Early Adopter
The timeseries command is a starting command of DQL. It combines loading, filtering and aggregating metrics data into a time series output.
-
Syntax
timeseries [column =] aggregation(metricKey [, default:] [, rollup:] [, rate:]) [, [column =] aggregation(metricKey, ...), ...] [, by:] [, filter:] [, interval: | bins:] [, from:] [, to:] [,timeframe:] -
Example 1
1timeseries usage=avg(dt.host.cpu.usage) -
Example 2
1timeseries 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 response
The 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 timeframe and interval.
Here is an example of the result of the timeseries command. Note that:
- the first aggregation column name has been specified in the query (
min_cpu) - the second aggregation column name has not been specified in the query, hence the name is derived from the expression (
max(dt.host.cpu.usage)) - the first aggregation does not specify a
defaultparameter, hence it can containnullfor empty time slots - the second aggregation does specify a
defaultparameter, hence the empty time slots are replaced with thedefaultvalue (99.9in this example)
| timeframe | interval | dt.entity.host | min_cpu | max(dt.host.cpu.usage) |
|---|---|---|---|---|
{"start":"2022-10-24T07:00:00","end":"2022-10-31T07:00:00"} | "1h" | HOST-1 | [35.1,35.9,35.5,36.7,...,37.9,39.4] | [36.9,37.8,38.8,38.8,...,38.6,39.5] |
{"start":"2022-10-24T07:00:00","end":"2022-10-31T07:00:00"} | "1h" | HOST-2 | [24.9,25.1,null,25.0,...,23.8,24.5] | [30.9,31.3,99.9,32.7,...,33.1,37.1] |
Aggregation
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
The 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 null.
Rate normalization
The 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 [12,12,24,36].
Time interval
The 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.
The interval and 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 bins or 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).
Rollup
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 host dimension, 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.
-
Example
The
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
The rollup parameter supports the following functions: min, max, sum, avg, and count.