Datasources

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, 6, 7, 8,10]. The percent(bps, 95) function will return 8 (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.