SNMP DEVICE - Transformation expressions

Christophe BENNOURINE

March 23, 2023 14:40

This step is optional (except with OID combinations).

Once you have selected your OID(s), it is possible to apply a treatment to it. For example:

Because some OID values are sometimes not very meaningful and difficult to use as they are.
To use the functions of the transformer, in particular to calculate a bandwidth from a network interface OID of a switch, router, etc.

The transformer will therefore allow you to write expressions to manipulate and format the OID values.

Good to know: To be processed with the transform expressions, the data must be received without unit. The unit will then be chosen via the drop-down list provided for this purpose.

In order to process the value of your OID in the transformer, you need to use the value() function.

value() (an alias of value(0) ) is a function that allows you to use the OID value to apply a transformation to it.

In the case where several OIDs have been selected, the corresponding values are accessible via the value(N) variables, where N is the index of the OID indicated in the list.

A "Paste into Transformation Expression" button allows you to automatically paste the correct variable into the expression input field.

Advanced functions are also available to allow or facilitate certain operations:

previousValue() returns the previously evaluated value.
growth() returns the difference between the last two evaluated values (equivalent to value() - previousValue() ).
elapsed() returns the time (in seconds) between the last two evaluations.
bandwidth() returns the bandwidth calculation (equivalent to growth() / elapsed() ), inferring that the associated OID is for a data volume (the basic unit is kept).
slice(value, start, end) returns a section of a string, from the indices "start" (inclusive) to "end" (exclusive). Negative indices will be treated as [string length + index], reversing the direction of extraction.
readByte(value, position) returns the decimal value of the byte at the given position (positive integer) of a string of bytes (OCTET_STR type), or, if no "position" is given, the hexadecimal value of the complete chain.
readBit(value, position) returns the value of the least significant bit at the given position (positive integer, read from the right). The value provided must be a decimal.

In the case of combined OIDs, the previousValue, growth, elapsed and bandwidth functions can be used on the OID of your choice by specifying its index as an argument.
Example: bandwidth(2) will return the bandwidth of the OID with index 2 in the left list.

The slice, readByte, and readBit functions must receive the return of another function as their first "value" parameter.

Example of expressions for the transformer

In the example below, a switch returns a value of "1", "2" or "3" to report the status of its power supply. The objective is to transform these numerical values into understandable text

Transforming a numerical value into a string of characters.

It is specified in the MIB that 1 = OK, 2 = Warning, 3 = Failed

value() == 1 ? "OK" : 
(value() == 2 ? "Warning" : 
(value() == 3 ? "Failed"))

Calculating a bandwidth

Calculate a bandwidth, based on an OID that provides the amount of data that has passed through a port (e.g. IfInOctets)

bandwidth()

Using combined OID's

Transform a combination of values (several OIDs combined):

(value(0) * value(1)) / value(2)

Other examples:

Transform a value based on a total of 255 to a percentage value	(value() * 100) / 255
Transform a value in bits to a value in bytes	value() * 8

Advanced functions:

readByte reads a string of bytes (OCTET_STR type). readByte(value(), p) The 1st argument must be the return of an existing function, such as value() which would return the value of an OCTET_STR type OID. The 2nd argument p is a positive integer designating the position of the byte that we wish to read, starting from 0. The return of the function will be a representation of the octer in decimal value.
The examples opposite assume that value() = \u0000\u001d\u0637"O or 001DD8B7224F in hexadecimal	readByte(value(), 1) will return 29, the decimal value corresponding to 1D (2nd byte).
	readByte(value(), 5) will return 79, the decimal value corresponding to 4F (6th byte).
	readByte(value()) will return 001DD8B7224F, which is the hexadecimal value corresponding to the entire byte string.
readBit reads a byte from a decimal value (representing a binary value). readBit(readByte(value(), 1), p) Reading is performed on the least significant bit, implying a reading direction from right to left. The 1st argument must be the return of an existing function, such as readByte(value(), 1) which would return the decimal value of an OCTET_STR type OID. The 2nd argument p is a positive integer designating the position of the byte that we wish to read, starting from 0 from the right. The return of the function will be a binary representation of the bit (0 or 1).
The examples opposite assume that readByte(value(), 1) = 29 or 00011101 in binary	readBit(readByte(value(), 1), 0) will return 1 (00011101), i.e. the 1st least significant bit (in position 0 from the right).
	readBit(readByte(value(), 1), 5) will return 0 (00011101), i.e. the 6th least significant bit (in position 5 from the right).
slice reads a sub-portion of string between two positions. slice(value(), x, y) The 1st argument x is an integer defining the starting position (inclusive). The 2nd argument y is an integer defining the end position (exclusive). For any negative x or y, the position will be interpreted as [string length + index], reversing the extraction direction.
The examples opposite assume that value() = "hello world"	slice(value(), 0, 5) will return "hello", i.e. the substring from the 1st character (inclusive) to the 6th character (exclusive).
	slice(value(), 6) will return "world", i.e. the substring from the 7th character (inclusive) to the end of the string, the end not having been specified. Equivalent to slice(value(), 6, 11)
	slice(value(), -10, -2) will return "ello wor", i.e. the substring from the 1st character (inclusive) to the 10th character (exclusive). The `hello world` string being of length 11, this is interpreted as: slice(value(), 11 + (-10), 11 + (-2)) or slice(value(), 1, 9)

Please see the context-sensitive help for more information on transformer expressions.

Output value

Finally, concerning the treatment of the data, it is possible to assign a unit to it, via the drop-down list located on the right-hand side:

As soon as a unit is selected, RG will automatically display the value with the most suitable unit (Kio, Mio, Gio... Year, month, week...).

SNMP DEVICE - Transformation expressions

Example of expressions for the transformer

Output value

📖 Articles in this section