Reference to the if() function

Summary

if(<conditionExpression>, <thenExpression>, [<elseExpression>])

Returns the points from thenExpression while conditionExpression returns non-zero values. Returns points from elseExpression otherwise.

Parameters

ParameterDescription
conditionExpression Expression describing the time series to be used as the condition. For example, if the condition is cpu.loadavg.1m>100, then the condition evaluates to true if the load is greater than 100, and to false otherwise.
This expression typically uses a comparison operator.
thenExpression Required expression that describes the time series to return when the condition is met.
  • If conditionExpression is true for a point, we return the corresponding point from thenExpression.
  • If conditionExpression is false for a point, we return nothing for that point.
elseExpression Optional expression that describes the time series to return when the condition is not met.
If you include elseExpression:
  • If conditionExpression is true for a point, we return the corresponding point from thenExpression, that is, we ignore elseExpression
  • If conditionExpression is false for a point, we return the corresponding point from elseExpression. That means we return return a continuous stream of points that change depending on the value of the condition.

Description

The if() conditional function returns data values based on the specified condition. You can determine what values are returned if the condition is true, and what values are returned if the condition is false. The Wavefront system treats a 0 value as false, and all other values as true.

Each of the expressions can be constant or a ts() expression (query).

Interpolation

We use interpolation to connect points in each of the expressions. We use interpolated values in conditionalExpression to determine whether to return values from thenExpression or elseExpression. For example:

  • Assume you have an if() query like the following:

    if(ts(my.metricA) > 0, ts(my.metricB), ts(my.metricC)).

  • my.metricA reports a value of 0 at 12:00pm and my.metricC reports values at 11:59am and 12:01pm.
  • Because my.metricA is false, we show my.metricCand we show an interpolated value for my.metricC at 12:00pm.

Series Matching and if()

We perform series matching when ts() expressions are used for 2 or more parameters.

For example, assume we have a query that’s structured like this:

if(ts(my.metricA) > 100, ts(my.metricB))

  • my.metricA describes 100 time series
  • my.metricB describes 50 time series,
  • If some elements in the my.metricA time series, for example, the hosts, map to elements in the time series in myMetricB, then we can return myMetricB time series for those series where my.metricA is greater than 100.
  • However, if the time series don’t include elements that map, then it’s not possible to determine what to return if the condition is met.

Examples

The following example set starts with a simple metric, which looks like this:

if metric

Now we use an if condition that returns a value of 50 for any point that’s greater than 100, and a value of 25 otherwise. Here, the behavior of the two time series diverges: For one, the value alternates between 25 and 50. The other time series is always greater than 100 and displays a single orange line.

if then else

Finally, we look at an example that does not use an else expression. For this case, we’ve limited the query to one time series, and we can see the interpolation that happens between the different true values.

if then