align¶

Description¶

Align raw metrics onto a time grid (defined by the input period) by aggregating nearby data points together. By default, align generates 300 bins.

If frame is not specified, align aggregates all points between two grid points (tumbling window aggregation). If frame is specified, align aggregates all data points that fall into a frame relative to each grid point (sliding window aggregation).

When options(bins: <N>) is specified, Observe will pick a user friendly bin size that produces at most N bins across the query window. And when it is set to 1, Observe will produce one single time bin that matches the query window exactly. This option is not accelerable as it is query window dependent.

When a min_bin option is specified, Observe will use the min_bin duration size for its bins if it is larger than the calculated bin duration. This option is not accelerable.

When options(empty_bins: true) is specified, Observe will produce output even for the bins that have no data. These output will always be null. This option is not accelerable.

Align is accelerable when the period argument is specified and the empty_bins option is not enabled.

Usage¶

align [ options ], [ period ], [ frame ], metricAligningExpression_1, metricAligningExpression_2, ...

Argument	Type	Optional	Repeatable	Restrictions
options	options	yes	no	constant
period	duration	yes	no	none
frame	frame	yes	no	constant
metricAligningExpression	expression	no	yes	none

Options¶

Option	Type	Meaning
bins	int64	Sets the maximum number of bins to produce (not accelerable)
min_bin	duration	Sets the minimum bin duration. If this value is larger than the calculated bin duration, the calculated bin duration will be used. (not accelerable)
empty_bins	bool	Generate output even for bins in the time window that have no data (not accelerable)

Accelerable¶

align is sometimes accelerable, depending on options used. A dataset that only uses accelerable verbs can be accelerated, making queries on the dataset respond faster.

Examples¶

align 5m, requests: rate(m("requests_total"))

Computes the per-second rate of “requests_total” metric for each 5m time bins.

align 5m, requests: rate(m("requests_total")), memory_used: avg(m("memory_used"))

Computes the per-second rate of “requests_total” metric and the average of “memory_used” metric, for each 5m time bins.

align 1m, frame(back: 10m), memory_used: avg(m("memory_used"))

Computes the moving average of “memory_used” metric in the past 10m, for each 1m step. Note that frame() may not be exact for better performance.

align 1m, frame_exact(back: 118s), memory_used: avg(m("memory_used"))

Computes the moving average of “memory_used” metric in the past exact 118s, for each 1m step.

align frame(back: 5m), requests: rate(m("requests_total"))

Computes the per-second rate of “requests_total” metric in the past 5 minutes, for each step. The step size will be determined dynamically to make the chart human-readable. It’s determined based on the query window and a number of other parameters such as chart resolution. This formulation is not accelerable.

align options(bins: 100), memory_used: avg(m("memory_used"))

Computes the average for each time-series of “memory_used” metric over time.

The time bin size will be determined dynamically to make the chart human-readable, and it will produce no more than 100 points for each time-series in the query window.

For example:

when query window is 1 hour, 1 minute bins will be produced
when query window is 4 hours, 5 minutes bins will be produced
when query window is 1 day, 30 minutes bins will be produced

This formulation is not accelerable.

align options(bins: 100, min_bin: 5m), memory_used: avg(m("memory_used"))

Computes the average for each time-series of “memory_used” metric over time.

Like in example 5, the time bin size will be determined dynamically to make the chart human-readable. The bins option overrides the default bin count and states that align will attempt to return 100 bins. Since the minimum bin size is set to 5 minutes by min_bin, if the calculated bin size is smaller than 5 minutes, a fixed bin size of 5 minutes will be used, even if this means fewer bins will be produced.

This formulation is not accelerable.

align options(bins: 1), memory_used: avg(m("memory_used"))

Computes the average for each time-series of “memory_used” metric during the query window.

This formulation is not accelerable.

align options(empty_bins: true), 5m, requests_per_second: rate(m("requests_total"))
make_col requests_per_second: if_null(requests_per_second, 0)

Computes the per-second rate of “requests_total” metric for each 5m time bins.

For the time bins where the metric was not reported, 0 will be used as the value: align will first generate null values for the requests_per_second column, which will then be replaced with 0 by the if_null() expression.

This formulation is not accelerable.