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)
Datapoint expressions support the typical operators you can find in most programming/scripting languages:
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".
In addition to using operators to perform calculations on numbers and datapoints, you can use the following functions in datapoint expressions:
The following comparison functions are available. Typically these are used within a conditional (if) statement.
A number of mathematical operations are available:
The following mathematical constants can be used:
Percentile functions are special functions that can be used only in virtual datapoint definitions (within graphs and widgets) -- not in complex datapoint expressions.
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
2. Add a virtual datapoint 95Out, with an expression of
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:
will not work, but
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.
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 are dealt with in two ways, as either part of a test condition, or as a result.
Consider the expression:
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.
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: