Summary
align(<timeWindow>,[mean|median|min|max|first|last|sum|count,] <tsExpression>)
align(<timeWindow>, <hsExpression>)
You can use align() with time series and with histograms.
| Time series function |
Groups the data values of a time series into buckets of size timeWindow, and returns one displayed value per bucket. Each returned value is the result of combining the data values in a bucket using the specified summarization method. |
| Histogram function |
Groups the distributions of a histogram series into time buckets of size timeWindow, and returns a single merged histogram distribution per bucket. In a time-series chart, align() displays just the median values of the resulting distributions. |
Parameters
Time-series Function
| Property | Description |
|---|---|
| timeWindow | Size (duration) of the buckets into which data values are grouped. You can specify a time measurement based on the clock or calendar (1s, 1m, 1h, 1d, 1w), the window length (1vw) of the chart, or the bucket size (1bw) of the chart. Default is minutes if the unit is not specified. |
| mean|median|min|max|first|last|sum|count | Summarization method to use for aggregating the data values within each bucket. These are similar to the Summarize by options that you can set for a chart. Default is mean (average). |
| tsExpression | Expression describing the time series to organize into buckets. |
Histogram Function
| Parameter | Description |
|---|---|
| timeWindow | Size (duration) of the buckets into which histogram distributions are grouped. You can specify a time measurement based on the clock or calendar (1s, 1m, 1h, 1d, 1w), the window length (1vw) of the chart, or the bucket size (1bw) of the chart. Default is minutes if the unit is not specified. |
| hsExpression | Expression describing the histogram series to organize into buckets. |
Description
You can use align():
- With time series.
- With histogram series.
Time-series Function
The align() time-series function adjusts the display of each time series described by the expression, by grouping the data values into buckets of the specified duration and then returning a single displayed value for each bucket.
By default, each returned value is the mean (average) of the values that were reported in a bucket. You can specify a different summarization method if you want the bucketed values to be aggregated in some other way (e.g. counted, summed, etc.). For example, if your time series reports data once a minute, but you want the data values to be displayed every 30 minutes (and summarized by median over that time window), use align(30m, median, ts(my.metric)).
align() returns values at intervals that start at the beginning of epoch time (Jan 1, 1970).
For example, align(2d, ts(my.metric)) produces a value at every 48-hour interval starting with 1970-01-01T00:00:00Z.
align() returns each value at the beginning of the interval that contains the data values it summarizes.
For example, suppose align(1m, sum, ts(my.metric)) returns a value at 10:05:00pm. This returned value is the sum of the values reported by my.metric from 10:05:00pm to 10:05:59pm.
Metrics are automatically pre-aligned for performance reasons when more than 100 time series are used in an aggregation function. You might see a pre-align warning even if you’re not using the align() function. You can ignore the warning in most cases, for instance, if a metric reflects a parameter changing over time.
You can use any supported unit of time for the timeWindow parameter. The bw unit, which stands for bucket window, enforces the summarization option in the query instead of the chart. For example, align(1bw, [{mean|median|min|max|first|last|sum},] <tsExpression>) produces a chart that looks identical, regardless of summarization method that you choose in the chart.
Using bw can also improve query performance on larger time windows where you normally align to a smaller interval like 1 minute. For example, rawsum(align(1m, <tsExpression>)) can be optimized by using rawsum(align(1bw, <tsExpression>)).
Histogram Function
The align() histogram function adjusts the granularity of each histogram series described by the expression. Within each series, align() groups the histogram distributions into buckets of the specified duration, and then merges the distributions in each group to produce a single composite distribution for each bucket. For example, align(1h, hs(my.hsMetric.m)) merges groups of per-minute distributions to produce hourly distributions.
This function merges the centroids and counts to produce composite histogram distributions.
You typically use align() as part of an input hsExpression that you specify to another histogram query function, for example, max(align(10m, hs(users.settings.numberOfApiTokens.m)))
You can visualize align() by running it as a top-level query under a time-series chart. Doing so displays a time series that consists of just the median values from the distributions in each returned histogram series. The chart for align(hs(my.hsMetric.m)) is the same as the chart for median(align(hs(my.hsMetric.m))).
Examples
Time-series Function
The following example shows a simple query for requests latency in a Stacked Column chart.
Next we put the results into 5 minute buckets.
Finally, we use max as the alignment algorithm. The default for align() is median()
Histogram Function
This chart represents the histogram series that is described by the expression hs(alerting.check.latency.m, customer="perftest"). The chart shows the histogram series as a line that consists of the median values of the distributions. The line contains one median value per minute.
Now we align the per-minute distributions into 10-minute buckets:
align(10m, hs(alerting.check.latency.m))
Aligning merges the histogram distributions “horizontally” to produce a less granular series of composite distributions. The chart displays the results as a single line that consists of the median values of the composite distributions. The line contains one median value every 10 minutes.
