Vunetrix Manual: Define Lookups

Vunetrix uses lookups for some sensor types with custom channels. In general, lookups map status values as returned by a device (usually integers) to more informative expressions that show you the status of a monitored device as a clear message. Additionally, lookups can define the sensor status that will be shown for certain status codes (similar as sensor channel limits can define a sensor status, too). For example, for a printer, Vunetrix can show a sensor in a yellow Warning status with channel values like "Toner Low" instead of simple status codes.

Lookups can be customized individually; you can define your own texts that will be shown in a sensor's channel. See section Customizing Lookups below.

Note: If a channel uses lookups, we strongly recommend you to control the sensor status only via the lookup definition and not to use channel limits! See also section Sensor Channels Settings.

Note: Lookups do not change data in Vunetrix's database, but they merely change the way sensor channels are shown. Any change to lookup definition files will apply to historic data as well as to live data.

Requirement: Channel Unit "Custom"

All channels with enabled Value Lookup need to use the channel Unit "Custom". For details, refer to section Sensor Channels Settings.

Gauges of Lookup Channels

Vunetrix can display gauges for channels which use lookups. We recommend staying below 120 lookup values in order to display informative gauges for primary channels. Non-primary channels have an upper limit of around 40 lookup values.

A Gauge Showing the Status of a Lookup Channel

Lookups Directory and Format

Lookups are defined in XML format in files ending in .ovl. Vunetrix's standard lookup files are located in the Vunetrix program directory in a sub folder named lookups. These files are maintained by Vunetrix itself. In each of the files lookups are defined for one or more sensors. Furthermore, the lookups folder contains a sub folder named custom to store your customized lookups.

The files follow a basic principle. For each numeric value you can define:

• A message that will be looked up and shown instead of the value
• The status the sensor will show

Example

The following code illustrates the lookup definition for the toner status of the SNMP HP LaserJet Hardware sensor:

<?xml version="1.0" encoding="UTF-8"?>
<ValueLookup id="oid.paessler.hplaserjet.tonerstatus" desiredValue="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PaeValueLookup.xsd">
 <Lookups>
         <SingleInt state="Ok" value="0">
                 Toner Okay
         </SingleInt>
         <SingleInt state="Warning" value="1">
                 Toner Low
                      </SingleInt>
         <SingleInt state="Error" value="2">
                 No Toner Cartridge Loaded
         </SingleInt>
 </Lookups>
</ValueLookup>

The schema in the example provides an insight how lookups are defined:

• The <?xml> tag in the first line defines the content as XML.
• The <ValueLookup> tag in the second line contains:
• The ID which will be shown in the Sensor Channels Settings.
• The desiredValue attribute contains the value which will be used for the calculation of the "Coverage". In this example, 1 is defined.
• The xsi attributes refer to Vunetrix's predefined XML schema definitions (which allow easy editing of lookup files with supported editors). We recommend using the default value.
• Between the tags <Lookups> and </Lookups> the particular lookups for the sensor data are defined:
• A lookup entry starts with a tag containing the type of the status value, the lookup type (in this example, this is always <SingleInt>).
• Separated by whitespace, the state attribute defines the status the sensor will show. Allowed values are: Ok, Warning, Error, and None ("None" will not trigger a status change).
• The value attribute defines which numeric value will trigger the lookup. This is the value that Vunetrix will receive from the device.
• The text defines the substitution text that will be shown instead of the value. For example, this can be a status message.
• The same way all other possible lookups are defined. The lookup definitions are closed by the tag </Lookups>. The file closes with </ValueLookup>.

 
In our example, the lookup file will have the following effect:

The XML Schema

An overall schema of the XML files containing the lookups definitions can be sketched like this:

<?xml version="1.0" encoding="UTF-8"?>
<ValueLookup id="..." desiredValue="..." xmlns="..." xsi="...">
 <Lookups>
         <SingleInt state="..." value="...">
                 status text
         </SingleInt>
         <BitField state="..." value="...">
                 status text
         </BitField>
         <Range state="..." from="..." to="...">
                 status text
         </Range>
         
         [several other lookup definitions]
 
 </Lookups>
</ValueLookup>

Since all the XML files containing lookup definitions are delivered in a pre-given schema as indicated above, it will be easy and comprehensible for you to customize lookups.

Customizing Lookups

There is a subfolder named \lookups\custom located in the Vunetrix program directory. In order to customize existing lookups, copy the desired lookup file from the lookups folder to the custom folder or create a new .ovl file there. When using the same ID in the ValueLookup tag, the files in the \lookups\custom folder will have a higher priority than the original files in the lookups folder. This way, your customizations will be handled preferably by Vunetrix instead of the original lookup settings. If you want to use custom lookup definitions in addition to the existing lookups, define a new ID in the lookup file which is not used by another lookup file. Vunetrix identifies lookup definitions via this ID, it does not use the file name.

Open the file with an XML or text editor and adjust the lookups to your personal preferences. You can define your own messages as well as you can customize sensor states for the particular return values. For example, if you do not want an "Error" status (i.e. a sensor Down status) for the return value "2" but only a warning, then you can replace "Error" with "Warning".

Note: The possible states are given in the LookupState.xsd file in the custom directory. Following the schema of the XML files that are delivered with Vunetrix enables you to edit the lookups in a safe way.
 

Example for Lookups Customization

For example (just for illustration purposes), imagine you would like to add the status "None" to the example above and change the status for the return value "2" from "Down" to "Warning". Then do the following:

• Copy the file oid.paessler.hplaserjet.tonerstatus to the \lookups\custom subfolder of your Vunetrix installation.
• Open this file with an editor.
• Leave the ID value unchanged to prioritize the customized lookup to the original file.
• Replace "Error" with "Warning" for value "2".
• Add a a "SingleInt" element with status "None" for the (hypothetical) return value "3".
• Save the file and reload the custom lookup folder in Vunetrix.

The customized lookup file will finally look like this:

<?xml version="1.0" encoding="UTF-8"?>
<ValueLookup id="oid.paessler.hplaserjet.tonerstatus" desiredValue="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PaeValueLookup.xsd">
 <Lookups>
         <SingleInt state="Ok" value="0">
                 Toner Okay
         </SingleInt>
         <SingleInt state="Warning" value="1">
                 Toner Low
                      </SingleInt>
         <SingleInt state="Warning" value="2">
                 No Toner Cartridge Loaded
         </SingleInt>
         <SingleInt state="None" value="3">
                 Unknown status of toner
         </SingleInt>
 </Lookups>
</ValueLookup>

desiredValue Attribute

It is necessary to define a desiredValue in the lookup files. The desiredValue corresponds to a status value triggering a lookup. Vunetrix calculates the percentage of time this specific state has been monitored. The result is displayed for all data tables and graphs that show averaged values.

Considering the example above where the desiredValue is "1", Vunetrix will calculate the percentage of time the toner status has been "Warning". If in a time span of five minutes four of five sensor scans returned a "Warning" status, Vunetrix would show an average of 80% for this time span, because in 80% of the time the sensor showed a "Warning".

Lookup Types: SingleInt, BitField, Range

Beside the lookup type SingleInt as seen above, there are two other lookup types: BitField and Range. Using these types you can define lookup values beyond simple integers.

Note: You can use only one kind of lookup type in one lookup file. For example, only SingleInts, BitField, or Ranges. Different lookup types in one file are not allowed.

Define Lookup Files in Sensor Channel Settings

For each sensor with a custom channel you can define a lookup file that will be used. This is done in a sensor's channel settings with an option called "Value Lookup". This option is visible for many SNMP sensors, some application sensors, and always for the following sensor types:

• EXE/Script Sensor
• EXE/Script Advanced Sensor (if a Custom unit is defined)
• SNMP Custom Sensor

For details, please see the Sensor Channel Settings section.

Loading Lookups

You can (re)load the defined lookups in the custom folder by clicking the Load Lookups button. This button can be found in Vunetrix under Setup | System Administration | Administrative Tools.

Debugging—What will happen if...?

• A return value is defined in the lookups that never will be returned by a device because the value is not assigned: The value will never be triggered, so Vunetrix will simply ignore this entry.
• Vunetrix receives a return value that is not defined for lookups: No substitution message can be found. Vunetrix will just show the return value.
• Different lookup types are in one lookup file: This is not allowed and Vunetrix will discard this lookup definition. If you use miscellaneous lookup types in one file, for example, ranges and singleInts together, the Vunetrix system will create a ticket when loading lookups or restarting the Vunetrix server with the following error message: Value lookup file "[...]" could not be loaded ("" is not a valid integer value)".
• Incorrect XML code: Vunetrix will create a new ticket when loading lookups or restarting the Vunetrix server with a corresponding error message and discard this lookups definition.

More

Wikipedia: Masks (computing)

• http://en.wikipedia.org/wiki/Bit_mask

Next Topic