Metrics API - Metric expressions

Metric expressions enable you to use simple arithmetic operations right in the metric selector.

For example, this expression calculates the ratio (as a percentage) of two metrics:

((metric1)/(metric2))*(100)

For the operands of the expression, you can use metrics or numbers.

  • Each operand must be wrapped in parentheses (). You can also use brackets to enforce precedence.
  • All metrics with more than 1 data point involved in a metric expression must be of the same resolution.
  • You can use any metric as an operand, including metrics modified by any transformation chain, and you can apply transformations to the result of the expression.

Limitations

The total length of the metricSelector string is limited to 5,000 characters.

You can query data points of up to 10 metrics in one query.

For the purposes of this limit, one expression (for example, (metric2)+(metric2)) counts as one metric.

Precedence

Standard mathematical precedence rules applies:

  1. Parentheses
  2. Negation
  3. Multiplication, division
  4. Addition, subtraction

Aggregation

If an aggregation has been applied in a transformation chain, this aggregation is used. If no transformation has been applied, the default aggregation is used. Your metric operands can be of different aggregations. For example, (metric:max)-(metric:min).

Expression resolution

Metric expressions are resolved as follows:

  1. Form tuple pairs for each pair of metrics.
  2. Align data points in every tuple.
  3. Apply arithmetic operation to aligned data points.

Tuples

Arithmetic operations use the data points of tuples (unique combinations of metric—dimension—dimension value) of metrics. Identical tuples of each metric are paired and then their data points are aligned.

If one metric is dimensionless (has just one tuple without dimensions and dimension values), then this single tuple is paired with every tuple of other metrics. The same applies to numbers.

Non-pairable tuples are ignored by the expression and are not presented in the result.

Data points

Once tuple pairs are formed, the data points are aligned, and then the desired arithmetical operation is applied to the aligned data points.

  • If any of the aligned data points is null, the expression resolves to null.
  • If a number is involved in the operation, it is aligned with every data point of the metric operand.
  • If one metric is a single data point and the other is a series, the single data point is aligned with every data point of the series.
  • If both metrics are a single data point, the data points are aligned and the resulting time slot covers both data points.
  • If both metrics are series, the data points are aligned by timestamps.

For any unaligned data points, the expression resolves to null.

Examples