Datapoint Expressions

Datapoint Expressions are used to define virtual datapoints in a graphs or widgets, or when defining standard complex datapoints in a datasource definition.

Expression Format

Datapoint expressions can be written in either Infix and RPN formats:

Infix:

``(sendpkts-recdpkts)/sentpkts*100``

RPN:

``sendpkts,recdpkts,-,sentpkts,/,100,*``

All examples below will be presented using the Infix format.

Expression Operands

There are three kinds of operands that can be used in datapoint expressions:

• datapoint names
• device property names
• any arbitrary numbers

The following example uses numbers and datapoint names to calculate the percentage of inbound packets discarded on a particular interface:

``100 * InDiscards/(InBroadcastPkts+InUcastPkts+InMulticastPkts+InDiscards)``

Expression Operators

Datapoint expressions support the typical operators you can find in most programming/scripting languages:

Arithmetic Operators

 x + y addition • 2 + 2 = 4 x - y subtraction • 3 - 2 = 1 x * y multiplication • 2 * 3 = 6 x / y division • 4 / 2 = 2 x % y modulus • 4 % 2 = 0

Bitwise Operators

 x & y bitwise and • 1010 & 1100 = 1000 x | y bitwise or • 1010 | 1100 = 1110

Logical Operators

 &&(expression1,expression2) or and(expression1,expression2) logical and: evaluates as true if both expression1 and expression2 are true (non-zero) • and(2+2,1+1) = true • and(2+2,2-2) = false ||(expression1,expression2) or or(expression1,expression2) logical or: evaluates as true if either expression1 or expression2 is true (non-zero) • or(2+2,1-1) = true • or(2-2,1-1) = false

Note that boolean data type is not supported in datapoint expressions. Instead, any non-zero value will be treated as true and zero will be treated as false. So, in the case where both operands are non-zero && / and will return "1". In the case where either operand is non-zero || / or will return "1".

Expression Functions

In addition to using operators to perform calculations on numbers and datapoints, you can use the following functions in datapoint expressions:

Conditional Syntax

 if(x,y,z) if expression x evaluates as true, return y; otherwise return z • if(0, 1, 2) = 2 • if(1, 1, 2) = 1

Comparison Functions

The following comparison functions are available. Typically these are used within a conditional (if) statement.

 lt(x,y) evaluates as true if x < y • lt(1, 2) = 1 le(x,y) evaluates as true if x <= y • le(3, 1) = 0 gt(x,y) evaluates as true if x > y • gt(2, 1) = 1 ge(x,y) evaluates as true if x >= y • ge(4, 1) = 1 eq(x,y) evaluates as true if x == y • eq(4, 1) = 0 limit(x,y,z) returns x if x is between y and z; otherwise NaN • limit(1, 2, 3) = NaN • limit(3, 1, 4) = 3 in(i [, j, ..., n], z) evaluates as true (1) if z is present in the list of possible values; otherwise returns false (0) • in(DatapointOne, DatapointTwo, DatapointThree, value) = 1 when any of the datapoints currently return "value" • in(value1, value2, value3, DatapointOne) = 1 when DatapointOne is currently returns any of the listed values max(x,y) returns the larger of x and y • max(1,2) = 2 min(x,y) returns the smaller of x and y • min(1,2) = 1 un(x) returns true (1) if x is unknown (not a number) • un(1) = 0

Mathematical Functions

A number of mathematical operations are available:

 round(x) rounds the value x to an integer value • round(1.89) = 2 floor(x) returns the previous smallest following integer of x • floor(2.78) = 2 ceil(x) returns the previous largest following integer of x • ceil(2.78) = 3 abs(x) returns the absolute value of x • abs(-3) = 3 log(x) returns the natural logarithm of x exp(x) returns the natural exponential of x (ex) pow(x,y) returns the result of raising x to the y power (xy) sqrt(x) returns the square root of x sin(x) returns the sine of x cosine(x) returns the cosine of x

Constants

The following mathematical constants can be used:

 unkn() returns NaN (not a number) pi() returns the value of pi e() returns the value of Euler's number (e) inf() returns the value of positive infinity neginf() returns the value of negative infinity random() returns a random number between 0 and 1

Percentile Functions

Percentile functions are special functions that can be used only in virtual datapoint definitions (within graphs and widgets) -- not in complex datapoint expressions.

 percent(x,y) returns the y percentile value of all available values of datapoint "x" for the displayed time range, using aggregated data rawpercentile(x,y) returns the y percentile value of all available values of named datapoint "x" for the displayed time range, using raw data

Percentile Function Examples

• Consider plotting an hourly graph for bandwidth (bps). In our database, we've collected 10 values for bps for this hour: [2, 3, 7, 6, 1, 3, 4, 10, 2, 4]. If we sort this array, they will be [1, 2, 2, 3, 3, 4, 4, 6, 7,10]. The percent(bps, 95) function will return 10 (the 9th value in the 0-based array) - meaning that 95%of the samples are below this value.

• As another example, to calculate the 95% traffic rate (using the max of the in and out 95% rate, as many ISPs do), you could add the following to the Throughput graph of the snmp64_If- datasource:

1. Add a virtual datapoint 95In, with an expression of

``percent(InMaxBits,95)``

2. Add a virtual datapoint 95Out, with an expression of

``percent(OutMaxBits,95)``

3. Add a virtual datapoint 95Percentile, with an expression of

``if(gt(95In,95Out), 95In, 95Out)``

This uses the value of 95In, if it is larger than the value of 95Out, else it uses the value of 95Out

4. Add the graph line 95Percentile to plot the 95% line in whatever color you choose.

• Also, note that percentile functions require that x is a datapoint rather than an expression. Meaning:

``percent(InOctets*8, 95)``

will not work, but

``percent(InOctets, 95)``

will. To implement the former, first create a virtual datapoint containing the mathematical expression and use that datapoint as an argument to the percentile function.

Special Cases

Negative Values

Datapoint expressions cannot start with a negative sign. To use a negative value in an expression, subtract the value from zero (e.g. use 0-2 rather than of -2).

Unknown Values

Unknown values are dealt with in two ways, as either part of a test condition, or as a result.

Consider the expression:

``if(un(DatapointOne),0,DatapointOne)``

In this case, the expression will return 0 if the value of DatapointOne is unknown (NaN -- not a number, such as absence of data, data in non-numerical format, or infinity). If the value of DatapointOne is anything other than NaN (an actual number) then that number will be returned.

Next, consider:

``if(lt(DatapointTwo,5),unkn,DatapointTwo)``

This expression will return NaN (which will be displayed as "No Data") if the value of DatapointTwo is less than number 5. If DatapointTwo returns value greater than 5, then that value will be displayed.

NaN values also need special consideration when used with operations that only return true/false. Java language specification dictates that logical expressions will be only evaluated as the result true or false even if one of the operands is NaN. For example, the expression eq(x,y) will always be evaluated as a result of 0 or 1 even if the x and/or y is NaN.

To work around this, you can check the values before performing are NaN before the expression evaluation.

if(or(un(Datapoint1), un(Datapoint2)), unkn(), <expression to evaluate>)

Below is a list of operator/function behavior with NaN values:

 Arithmetic Operators +, -, *, /, % Behavior with NaN ValuesReturns NaN Bitwise Operators&, | Behavior with NaN ValuesReturns non-NaN Logical Operatorsand, or, xor Behavior with NaN ValuesReturns 0 or 1 Conditional Exprif(x,y,z) and x is NaN Behavior with NaN ValuesReturns z Comparison Funclt, le, gt, ge, eq, in Behavior with NaN ValuesReturns 0 or 1 Mathematical Funcmin, max, sin, cos... Behavior with NaN ValuesReturns NaN