Summary
count(<tsExpression>[, metrics|sources|sourceTags|pointTags|<pointTagKey>])
count(<hsExpression>)
count(<eventsExpression>)
You can use count() with time series, with histograms, and with events.
| Time series aggregation function |
Returns the number of reporting time series described by the tsExpression at each moment in time.
A time series is counted as reporting even if it has interpolated values.Use the mcount () function, if you want to add together the number of data points reported by a time series over a shifting time window.
|
| Histogram conversion function |
Returns time series that consist of the number of values in each histogram distribution described by the hsExpression. |
| Event conversion function |
Returns a single time series that reports the number of event boundaries that occur in eventExpression over time. |
Parameters
Time-Series Aggregation Function
| Parameter | Description |
|---|---|
| tsExpression | Expression describing the set of time series to be counted. |
| metrics|sources|sourceTags|pointTags|<pointTagKey> | Optional group by parameter for organizing the time series into subgroups and then returning a count for each subgroup.
Use one or more parameters to group by metric names, source names, source tag names, point tag names, values for a particular point tag key, or any combination of these items. Specify point tag keys by name. |
Histogram Conversion Function
| Parameter | Description |
|---|---|
| hsExpression | Expression describing the histogram distributions to obtain the number of values from. |
Events Conversion Function
| Parameter | Description |
|---|---|
| eventExpression | Expression describing the events to count over time. |
Description
You can use count():
- With time series as an aggregation function for time series.
- With histogram series as a conversion function.
- With event sets as a conversion function.
Time-Series Aggregation Function
The count() aggregate function adds together the number of reporting time series represented by the expression, at each moment in time.
By default, count() produces a single count across all time series. You can optionally group the time series based on one or more characteristics, and obtain a separate count for each group.
If a time series has data gaps, count() fills them in by interpolation whenever possible. A time series with an interpolated value is considered to be reporting and is included in the current count. When a value cannot be interpolated into a time series (or if the series stops reporting altogether), the series is excluded from the count.
Grouping
Like all aggregation functions, count() returns a single series of results by default.
You can include a group by parameter to obtain separate counts for groups of time series that share common metric names, source names, source tags, point tags, or values for a particular point tag key.
The function returns a separate series of results corresponding to each group.
You can specify multiple ‘group by’ parameters to group the time series based on multiple characteristics. For example, count(ts("cpu.cpu*"), metrics, Customer) first groups by metric names, and then groups by the values of the Customer point tag.
zone and ZONE, when you use an aggregation function and apply grouping, we will consider zone and ZONE as separate tags. Interpolation
If any time series has gaps in its data, the query engine attempts to fill these gaps with interpolated values before applying the function. A value can be interpolated into a time series only if at least one other time series reports a real data value at the same moment in time.
Within a given time series, an interpolated value is calculated from two real reported values on either side of it. Sometimes interpolation is not possible–for example, when a new value has not been reported yet in a live-view chart. In this case, the query engine finds the last known reported value in the series, and assigns it to any subsequent moment in time for which a real reported data value is present in some other time series. We use the last known reported value only if interpolation can’t occur and if the last known reported value has been reported within the last 15% of the query time in the chart window.
You can use rawcount() to suppress interpolation. See Standard Versus Raw Aggregation Functions.
Histogram Conversion Function
The count() histogram conversion function returns the number of data values in each distribution of each histogram series that is represented by the expression. The counts for a given histogram series are returned as a separate time series that contains a data point corresponding to each input distribution.
count() is a histogram conversion function because it takes histogram distributions as input, and returns time series. You can therefore use a histogram conversion function as a tsExpression parameter in a time series query function.
Events Conversion Function
The count() events conversion function returns a single time series in which each data point reports the number of event boundaries in eventExpression at that moment in time.
The number of event boundaries at a particular moment in time is equal to: the number of events that started at that time, minus the number of events that ended at that time. Instantaneous events are represented as a single “0” value: 1 started minus 1 ended (instantaneous events are defined as events having their end time equal to their start time).
Examples
Time-Series Aggregation Function
The following examples contrast the result you get for two different types of servers. We’re using a Single Stat View chart to first get a count of all servers that have a sample requests latency and the source app-1* (11 servers). Then we get a count of all servers that have the source app-2* While the example is a bit contrived, it illustrates how to use the function.
The following Stacked Area chart groups all sources whose name starts with "app-1*" by the env point tag. The chart shows that 1 server is tagged with dev and 10 servers are tagged with production.
Histogram Conversion Function
The following example shows the result of applying count() to an hsExpression. As the legend shows, the distribution at 2:40p summarizes 3 values.
Note: count() returns a separate time series for each input histogram series. In this example, the hsExpression represents a single histogram series, so the result is a single time series. (In contrast, when count() is used as an aggregation function with a tsExpression, a single returned time series might be the result of counting multiple input time series.)
Caveats
Count is not a static number, it will change if the number of hosts reporting the metric changes. For some types of analysis, it is better to use avg() instead of count().