Advanced Topics

PRTG Manual: Define Lookups

PRTG uses lookups for some sensor types and for some sensors with custom channels. In general, lookups make data more human friendly because they map status values as returned by a device (usually integers) to more informative expressions in words that show you the status of a monitored device as a clear message.

Additionally, lookups can also define the sensor status that will be shown in correlation with certain status codes, just like sensor channel limits can define a sensor status, too. For example, for a printer, PRTG can show a sensor in a yellow Warning status with channel values, provided by lookups, like "Toner Low" instead of simple status codes, like "1".

You can customize lookups individually and define your own texts that a sensor channel can show. See the section Customizing Lookups below.

If a channel uses lookups, you can individually define how to control the sensor status, either using the lookup definition or using limits for numerical values returned by the device. For details, see Sensor Channel Settings, section Alerting and Limits.

Lookups do not change data in the PRTG database, 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.

Some exceptions apply to the SNMP Custom String Lookup sensor that basically does an "inverse lookup". It does not map an integer to a text message but only looks for matching strings in the lookup definition and shows a status based on this text value.

Customizing lookups is not possible on PRTG hosted by Paessler.

Here are quick links for ease of use.

• Requirement: Channel Unit "Custom"
• Visualization of Lookup Channels
• Lookups Directory and Format
• The XML Schema
• Customizing Lookups
• desiredValue Attribute
• Lookup Types: SingleInt, Boolean, BitField, Range
• Define Lookup Files in Sensor Channel Settings
• Loading Lookups
• Debugging—What will happen if...?

Requirement: Channel Unit "Custom"

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

There are sensors that provide the unit Value Lookup for channels in their sensor settings. Do not use the "custom" unit for channels of these sensors if you want to use lookups! This would result in malfunctioning lookup channels. For the following sensor types, choose the unit Value Lookup in the sensor settings and select your lookup file directly when adding the sensor:

• Google Analytics sensor
• Microsoft SQL v2 sensor
• MySQL v2 sensor
• Oracle SQL v2 sensor
• PostgreSQL sensor
• SNMP Custom Advanced sensor
• SNMP Custom Table sensor

Visualization of Lookup Channels

PRTG can display channels that use lookups as follows.

You can view the messages for the different lookups by hovering over the respective color section.

To see at one glance which lookup values in which channel are in Warning or Down status, check the sensor message on the Overview tab:

We recommend that you stay below 120 lookup values to display visually informative gauges for primary channels. Non-primary channels have an upper limit of around 40 lookup values for gauges.

The various states displayed in gauges always follow the clockwise order Up (green) < Warning (yellow) < Down (red) < Unknown (gray / black). This clockwise order by colors stays the same, no matter what numeric value a state has in the lookup definition. See the following example:

<?xml version="1.0" encoding="UTF-8"?>
  <ValueLookup id="example.lookups" desiredValue="1" undefinedState="olsWarning" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="PaeValueLookup.xsd">
    <Lookups>
      <SingleInt state="Ok" value="1">
        Works
      </SingleInt>
      <SingleInt state="Ok" value="2">
        Works a bit
      </SingleInt>
      <SingleInt state="Warning" value="4">
        Is slow
      </SingleInt>
      <SingleInt state="Error" value="8">
        Does not work
      </SingleInt>
      <SingleInt state="Ok" value="16">
        Works sometimes
      </SingleInt>
    </Lookups>
  </ValueLookup>

Even though the value 8 comes before the value 16, the state OK is shown before the state Error.

See Lookups Directory and Format and The XML Schema for more information about the lookup code and format.

Lookups Directory and Format

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

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

• A message that the sensor will look up and show instead of the numerical value
• The status that the sensor will show

Use the SNMP Custom String Lookup sensor to map a string into a corresponding status. Please use the lookup type SingleInt for this purpose.

You cannot access this directory on PRTG hosted by Paessler instances.

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 that is shown in the Sensor Channel Settings.
• The desiredValue attribute contains the value that is used for the calculation of the "Coverage". In this example, 1 is defined as desired value.
• The xsi attributes refer to the predefined XML schema definitions in PRTG (which allow easy editing of lookup files with supported editors). We recommend that you use 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" does not trigger a status change).
• The value attribute defines which numeric value will trigger the lookup. This is the value that PRTG will receive from the device.
• The text defines the substitution text that is 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 exemplary schema of the XML files containing the lookup definitions can look like this:

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

Because all the XML files containing lookup definitions are delivered in a pre-given schema as indicated above, you can customize lookups accordingly.

Customizing Lookups

If you want to change the status definitions of a specific sensor channel, you basically have to do the following:

1. Find out the (file) name of the lookup file in the settings of the sensor channel you want to change the behavior for.
2. From the PRTG program directory subfolder \lookups, copy this file into the \lookups\custom subfolder (ensure you do not change the file name!).
3. Change the duplicated file as you like. See the example below.

This feature is not available in PRTG hosted by Paessler.

All default lookup files are located in the \lookups subfolder in the PRTG program directory. To customize existing lookups, copy the desired lookup file from the lookups folder to the \lookups\custom subfolder 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, PRTG handles your customizations preferentially 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 that is not used by another lookup file. PRTG 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 customize sensor states for the particular return values. For example, if you do not want to show an "Error" (a sensor Down status) for the return value "2" but only a warning, then you can replace "Error" with "Warning".

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 PRTG enables you to edit the lookups in a safe way.

If you imported an oidlib file that contains lookups (you can see this in section Lookup in the MIB Importer), you can define your own sensor states for returning values. If you add an SNMP Library sensor using this oidlib, PRTG will create a lookup definition file using the lookupname of the chosen library as id parameter. Override this lookup definition with your own custom lookup as described in this section. This is important because lookups that are added via an oidlib will not contain any status definitions and result in a Warning status of the sensor by default because of the entry undefinedState="Warning".

If you use an SNMP Custom String Lookup sensor, you can create a new custom lookup definition in the \lookups\custom directory with the expected return values. In this case, use the lookupname of the chosen library as id parameter to override the lookups from the oidlib file.

When you save an edited lookup, make sure that it is saved as an .ovl file. Otherwise, the lookup might accidentally be saved as a .txt file and might not be loaded.

Example for Lookups Customization

For example (just for illustration purposes), imagine you would like

1. to have the status "Warning" for all undefined values that the target device might return,
2. to change the status for the return value "2" from "Down" to "Warning", and
3. to add the status "None" to the example above.

Then do the following:

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

The customized lookup file will finally look like this:

<?xml version="1.0" encoding="UTF-8"?>
<ValueLookup id="oid.paessler.hplaserjet.tonerstatus" desiredValue="1" undefinedState="Warning" 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>

See also SNMP Custom String Lookup Sensor—Example for a lookup definition that maps a string value to a sensor status.

desiredValue Attribute

It is necessary to define a desiredValue in the lookup files. The desiredValue corresponds to a status value triggering a lookup. PRTG calculates the percentage of time this specific status 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", PRTG 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, PRTG would show an average of 80% for this time span because 80% of the time, the sensor showed a "Warning".

Lookup Types: SingleInt, Boolean, BitField, Range

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

You can use only one kind of lookup type in one lookup file. This means, only SingleInt, only Boolean, only BitField, or only Range. 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 to use with the option Value Lookup in the sensor channel settings. 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, see section Sensor Channel Settings.

Loading Lookups

You can (re)load the defined lookups in the custom folder by clicking the Load Lookups and File Lists button in the PRTG web interface under Setup | System Administration | Administrative Tools.

A sensor whose lookup file you have modified and reloaded will not re-evaluate this lookup before the next sensor scan. For sensors with large scanning intervals, use the Scan Now option from the context menu to immediately apply the new lookup definition and to avoid an incorrect sensor status.

Debugging—What will happen if...?

• A return value is defined in the lookups that will never be returned by a device because the value is not assigned: The value will never be triggered, so PRTG simply ignores this entry.
• PRTG receives a return value that is not defined for lookups: No substitution message can be found. PRTG will just show the return value. You can optionally define a status for unknown values with a definition of undefinedState in the ValueLookup element (see section Define Lookups—The XML Schema above).
• Different lookup types are in one lookup file: This is not allowed and PRTG will discard this lookup definition. If you use miscellaneous lookup types in one file, for example, ranges and singleInts together, the PRTG system will create a ticket when loading lookups or restarting the PRTG server with the following error message: Value lookup file "[...]" could not be loaded ("" is not a valid integer value)".
• XML code is incorrect: PRTG will create a new ticket when loading lookups or restarting the PRTG server with a corresponding error message and discard this lookup definition.
• A lookup file has a file ending other than .ovl: The file will not be loaded.
• Alerting is disabled or based on limits: Error and warning states defined in the lookup will not apply. Please ensure you choose the option Enable alerting based on lookups in the channel settings if you want to use the lookup definition to control the sensor status.
• If you define a scaling factor in channel settings, it will not modify the values that are defined by lookups. Any applied lookup always uses the raw value as retrieved from the target device. If you use a scaling factor for such a channel, you will notice the scaling in data graphs, but the channel value will appear unmodified in data tables.

More

Video Tutorial: How to configure lookups in PRTG Network Monitor

• https://www.paessler.com/support/videos/prtg-advanced/prtg-lookups

Wikipedia: Masks (computing)

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

 

Advanced Topics

• Active Directory Integration
• Application Programming Interface (API) Definition
• Filter Rules for xFlow, IPFIX, and Packet Sniffer Sensors
• Channel Definitions for xFlow, IPFIX, and Packet Sniffer Sensors
• Define IP Ranges
• Define Lookups
• Regular Expressions
• Add Remote Probe
• Failover Cluster Configuration
• Data Storage
• Using Your Own SSL Certificate
• Calculating Percentiles