PRTG Manual: Define Lookups

PRTG uses lookups for some sensors and for some sensors with custom channels. In general, lookups map status values as returned by a device (usually integers) to more informative expressions in words. Additionally, lookups can define a shown sensor status based on the status value returned by a device, just like channel limits can define a sensor status, too. For a printer that returns the status value "1", for example, PRTG can show a sensor in the yellow Warning status with the text message "Toner Low" instead of only displaying the status value "1".

You can customize lookups by defining your own text messages that a channel shows and mapping them to a certain sensor status. See section Customizing Lookups.

If a sensor's channels use lookups, you can individually define how to control the sensor's status, either using the lookup definition or using limits for numerical values returned by the device. For details, see section Channel Settings, section Alerting and Limits. It is not possible to use both definitions at the same time.

i_round_blueLookups do not change data in the PRTG database, they merely change the way channels are shown. Any change to lookup definition files applies to historic data as well as to live data.

i_round_blueSome 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.

i_podTo upload customized lookups to PRTG hosted by Paessler, contact the Paessler support team.

In this section:

Requirement: Channel Unit "Custom"

All channels with an enabled Lookup need to use the Channel Unit "Custom". For details, see section Channel Settings.

i_round_redThere are sensors that provide the Channel Unit "Lookup" in their settings. Do not use the Channel Unit "Custom" for channels of these sensors if you want to use lookups. This would result in malfunctioning lookup definitions. For the following sensors, select the Channel Unit "Lookup" in the settings and select your lookup file directly under Channel Lookup when adding the sensor:

Visualization of Lookup Channels

PRTG can display channels that use lookups as follows.

Lookup Type

Visualization

Example

SingleInt, Range

Gauge

A Gauge Showing the Status of a Lookup Channel

A Gauge Showing the Status of a Lookup Channel

Boolean

Switch

A Switch Showing the Status of a Boolean Lookup Channel

A Switch Showing the Status of a Boolean Lookup Channel

BitField

Toggles

Toggles Showing the Status of a BitField Lookup Channel

Toggles Showing the Status of a BitField Lookup Channel

You can view the text messages for the different lookup values by hovering over the respective color section.

Gauge Showing the Respective Lookup Message when Hovering over a Color Section

Gauge Showing the Respective Lookup Message when Hovering over a Color Section

To see which lookup value in which channel shows the Warning or Down status, check the sensor message on a sensor's Overview tab:

Sensor Message in the Overview Tab

Sensor Message in the Overview Tab

i_round_blueWe 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.

Gauge Showing 120 Lookup Values

Gauge Showing 120 Lookup Values

i_round_redThe various sensor states that are displayed in gauges always follow the clockwise order Up (green) < Warning (yellow) < Down (red) < Unknown (gray). This clockwise order by colors stays the same, no matter which numeric value is mapped to which sensor status 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" (shown as the Up status) is displayed before the state "Error" (shown as the Down status).

i_square_cyanSee 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 Extensible Markup Language (XML) format in files ending with .ovl. PRTG standard lookup files are located in the \lookups subfolder of the PRTG program directory. These files are maintained by PRTG itself. In each of the files, lookups for one or more sensors are defined. Furthermore, the \lookups subfolder 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 looks up and shows instead of the numeric value itself.
  • The status that the sensor shows.

i_round_blueUse the SNMP Custom String Lookup sensor to map a string to a corresponding status. For this purpose, use the lookup type SingleInt.

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

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>
         <SingleInt state="..." value="...">status text</SingleInt>
         <SingleInt state="..." value="...">status text</SingleInt>
 </Lookups>
</ValueLookup>

Element

Description

Attributes, Value Assignment, and Content

<?xml>
content

This is the XML declaration that every .xml file begins with.

  • version and encoding are "1.0" and "UTF-8" respectively
  • content: <ValueLookup>contentValueLookup</ValueLookup>

<ValueLookup>
contentValueLookup
</ValueLookup>

Defines the ID of the channel, which desiredValue is used, the status for undefined values (undefinedState), and links to the predefined schema definitions in PRTG that allow editing of lookup files with supported editors.

  • id: Specifies how the name of the lookup file is shown in the channel settings.
    i_round_blueThe id is parsed as a lowercase string.
  • desiredValue: Contains the value used for the calculation of the "Coverage".
  • undefinedState: Optionally define a status for values that are not defined in the lookup file. If the target device returns a value that is not included in the lookup definition, the sensor shows this status (Ok, Warning, Error, or None) with an according message. Without a definition of "undefinedState", the sensor only shows the returned value.
  • xmlns:xsi/xsi: Refers to predefined XML schema definitions in PRTG (which allow editing of lookup files with supported editors).
  • contentValueLookup: Lookup definitions
    <Lookups>contentLookups</Lookups>

<Lookups>
contentLookups
</Lookups>

Defines the particular lookups for the sensor data.

  • contentLookups: One or more lookup entries, see below.

<SingleInt>
status text
</SingleInt>

<Boolean>
status text
</Boolean>

<BitField>
status text
</BitField>

<Range>
status text
</Range>

Each element defines one lookup entry. There can be one or more lookup entries from the same lookup type.

i_round_redYou 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.

The notation for the different lookup types can vary:

  • <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>
  • state: Defines the status the sensor shows. Allowed values are Ok, Warning, Error, and None ("None" does not trigger a status change).
    i_round_redState values must be capitalized for the sensor to work properly.
  • value: Defines the value that triggers the lookup. Enter an integer value.
    i_round_redRange always needs both values "from" and "to".
  • status text: Defines a status text that is used as substitution text and shown instead of the integer value, for example, a status message.

i_round_redThe SNMP Custom String Lookup sensor maps the status text to one of the specified states. For this sensor, use SingleInt.

Because all .xml files containing lookup definitions are delivered in a previously specified schema as indicated above, you can customize lookups accordingly.

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>

In our example, the lookup file has the following effect:

Value as Reported from HP Printer

Text Shown in PRTG (Channel)

Sensor Status Shown in PRTG

0

Toner Okay

i_status_green

Up

1

Toner Low

i_status_yellow

Warning

2

No Toner Cartridge Loaded

i_status_red

Down

Customizing Lookups

i_podTo upload customized lookups to PRTG hosted by Paessler, contact the Paessler support team.

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

  1. Find out the (file) name of the default lookup file in the settings of the channel that you want to change the behavior for.
  2. From the \lookups subfolder of the PRTG program directory, copy this file into the \lookups\custom subfolder. Make sure that you do not change the file name.
    OR
    create a new .ovl file there.
    i_round_blueWhen using the same ID in the ValueLookup tag, the files in the \lookups\custom subfolder have a higher priority than the original files in the \lookups folder. This way, PRTG prefers your customizations to the original lookup settings. If you want to use custom lookup definitions in addition to the standard lookups, define a new ID in the lookup file that is not used by any other lookup file. PRTG identifies lookup definitions via this ID, it does not use the file name.
  3. Open the file with an XML or text editor and customize the lookups as you like. You can define your own text messages or customize sensor states for particular return values. For example, if you do not want a sensor to show the Down status for the return value 2 but only the Warning status, replace the state "Error" with "Warning".

i_round_blueAll possible states are specified in the LookupState.xsd file in the custom directory. Following the schema of the .xml files that are delivered with PRTG ensures that you edit lookups in a safe way.

i_round_blueIf you imported an .oidlib file that contains lookups (you can see this in section Lookup in MIB Importer), you can define your own sensor states for returning values. If you add an SNMP Library sensor using this .oidlib file, PRTG creates 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 file do not contain any status definitions and result in the Warning status of the sensor by default because of the entry undefinedState="Warning".

i_round_blueIf you use an SNMP Custom String Lookup sensor, you can create a new custom lookup definition in the \lookups\custom subfolder 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.

i_round_redWhen 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 (for illustration purposes only), imagine you want

  • the sensor to show the Warning status for all undefined values that the target device might return,
  • to change the shown status for the return value "2" from the Down to the Warning status, and
  • to add the state "None" (shown as the grey Unknown status) to the example above.

Then take the following steps:

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

The customized lookup file looks 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>

i_square_cyanSee also the SNMP Custom String Lookup sensor 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 that triggers a lookup. PRTG calculates the percentage of time this specific status was 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 calculates the percentage of time the toner status showed the Warning status. If during a time span of five minutes, four of five sensor scans returned "Warning", PRTG would show an average of 80% for this time span because 80% of the time, the sensor showed the Warning status.

i_round_redThe desiredValue attribute always has to be an integer value. For the lookup type range, use an integer that you defined for one of your "from" or "to" parameters in the lookup file.

i_square_cyanFor more information, see also the Knowledge Base: Can I graph text values?

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.

Lookup Type

Description

Syntax

SingleInt

Use an integer to define a lookup for one status value.

value="int"

i_round_redThe full 32-bit integer range is supported.

Boolean

Use 0 or 1 to define a lookup for two different status values.

value="0"
value="1"

BitField

Use a bitfield for multiple status values.

Only use this lookup type if you have some basic knowledge about bitmasks. See section More for a general introduction.

i_round_redEvery value has to equal a power of two (for example, 1, 2, 4, 8, 16, 32, 64, etc.).

i_round_redThe SNMP Custom String Lookup sensor does not support BitFields.

Range

Uses an inter range from-to to define a lookup for several status values.

from="int" to="int"

i_round_redUsing ranges, the parameters "from" and "to" always have to be defined. If you want to query only one single value in a range file, this value must be set as a parameter for "from" and "to" (for example, from="2" to="2"). See also the Knowledge Base: Custom lookup range.

i_round_redThe SNMP Custom String Lookup sensor does not support ranges.

i_round_redThe full 32-bit integer range is supported.

i_round_redYou 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 Channel Settings

For each sensor with a custom channel, you can define a lookup file to use with the option Lookup in the channel settings. This option is visible for many SNMP sensors, some application sensors, and always for the following sensors:

i_square_cyanFor details, see section Channel Settings.

Loading Lookups

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

i_round_blueA sensor whose lookup file you have modified and reloaded does 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 happens if...?

  • a return value is defined in the lookups that is never returned by a device because the value is not assigned: The value is never triggered, so PRTG ignores this entry.
  • PRTG receives a return value that is not defined for lookups: No substitution message can be found. PRTG only shows the return value. You can optionally define a status for unknown values with a definition of undefinedState in the ValueLookup element (see section The XML Schema).
  • different lookup types are in one lookup file: This is not allowed and PRTG discards this lookup definition. If you use miscellaneous lookup types in one file, for example, ranges and singleInts together, PRTG creates a ticket when loading lookups or restarting the PRTG core server with the following error message: Lookup file "[...]" could not be loaded ("" is not a valid integer value)".
  • XML code is incorrect: PRTG creates a new ticket when loading lookups or restarting the PRTG core server with a corresponding error message and discards this lookup definition.
  • a lookup file has a file ending other than .ovl: The file is not loaded.
  • alerting is disabled or based on limits: "Error" and "Warning" states defined in the lookup do not apply. Make sure that you select the option Enable alerting based on lookups in the channel settings if you want to use lookup definitions to control the sensor status.
  • you define a scaling factor in channel settings: This does 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 notice the scaling in data graphs, but the channel value appears unmodified in data tables.

More

i_square_blueKNOWLEDGE BASE

Custom lookup range

Can I graph text values?

 

i_playVIDEO TUTORIAL

How to configure lookups in PRTG

 

i_toolsPAESSLER TOOLS

MIB Importer

 

i_square_blueMISCELLANEOUS

Wikipedia: Mask (computing)

Advanced Topics