Probe Variables

InterMapper can retrieve MIB variables from a device and then test them against thresholds. The <snmp-device-variables>section defines the OIDs of MIB variables that are to be retrieved. These values are called probe variables and can then be compared to thresholds to create alarms, warnings, etc.

Each line of the <snmp-device-variables>section defines a particular variable to be retrieved. The definition is composed of four comma-separated attributes: the variable's name, its OID, its Type, and an optional Chart legend. Their definitions are:

• VariableName is the name used to represent the particular MIB value in this probe. A VariableName consists of letters, digits and an underscore, and must begin with a letter. VariableNames are not case-sensitive. These variable names will be represented in the probe as $VariableName. It is not necessary that a particular VariableName match the corresponding name in the MIB, although that is definitely convenient.
  
  Note: Versions of InterMapper prior to 4.2 required that variable names be enclosed in curly braces, e.g., ${VariableName}. This not necessary in version 4.2 and later, and both forms are now identical.

• OID is the Object ID for the particular probe variable. The OID can be expressed as a string of dotted numbers or as an OID name, if the corresponding MIB has been imported into InterMapper. An OID can also be an expression, if the type is "CALCULATION" (see note below).
  
  Notes:
  • Calculation variables have a slightly different form, as described below.
  • See Probe Calculations for a description of the functions and operators that are available in expressions. A scalar's OID must end in ".0" according to the SNMP specifications. See SNMP OIDs for a description of allowable formats for OIDs
  • See On-Demand SNMP Tables for a description of how your probe can display tabular information from a MIB.
  • When InterMapper retrieves a value, by default it issues an SNMP Get-Next-Request for the previous OID, unless the pdutype is set to "get-request" (see Probe Properties for details.)
    
    
• Type - may be one of the following:
  • Default - InterMapper deduces an applicable type from the SNMP type of the variable and displays it according to the "Format for DEFAULT types" table below.
  • Integer - values are coerced to a numeric value. If you have a string value returned "78Fred", the value as INTEGER will be 78.
  • Hexadecimal* - is displayed as "0x" followed by pairs of hex digits separated by a space.
  • Hexnumber - converts a string of hexadecimal digits into a number. For example, a string value of "FE" would be converted to the number 254.
  • Double - converts a string to the corresponding floating point number. Thus a string of "5.678" will be represented internally as a floating point number between 5 and 6, and displayed
  • Total-value - displays the actual value of a counter or gauge, not a computed rate value. This will always be an unsigned number.
  • Per-second and Per-minute - force InterMapper to compute a rate for the particular variable by computing the difference between two successive samples and dividing by the elapsed time.
  • String* - sets a variable to the text string that corresponds to this OID's enumerated type, as defined in the MIB. (see below)
  • Calculation - sets the variable to the result of the calculation shown in the OID field.
  • TrapVariable - sets a variable based on the value received from an SNMP trap. A complete discussion of Trap Variables is available in About Custom SNMP Trap Probes.
    
    * STRING and HEXADECIMAL are both strings; they can't be charted.
    
    Format for DEFAULT types:
    

    If the variable is of type...	InterMapper will display it as:
    Counter32, Counter64	=> Per-Second
    Unsigned32 (Gauge)	=> Total-Value
    Integer	=> Integer
    OctetString	=> String (if first digit printable) or Hexadecimal (if not)
    Object ID	=> String
    IPAddress	=> String
    TimeTicks	=> String

    
    
• Chart-legend is an optional field that provides a text label to be placed on any strip charts that incorporate this variable. Chart legends may contain embedded variable names in the form $VariableName.

Here is a sample <snmp-device-variables>section.

<snmp-device-variables>    --Variable-name OID --- TYPE ---- CHART LEGEND ------    ipForwDatagrams, 1.3.6.1.2.1.4.6.0, PER-SECOND, "Forwarded datagrams"    ipInHdrErrors, 1.3.6.1.2.1.4.4.0, PER-MINUTE, "IP received header err"    tcpCurrEstab, 1.3.6.1.2.1.6.9.0, DEFAULT, "Number of TCP conn's"    sysDescr, 1.3.6.1.2.1.1.1.0, DEFAULT    -- Non-polled values:-- Calculation variables are computed each poll time    SineValue, (10*sin(0.01*time())), CALCULATION, "10 * sin(0.01 * time())" </snmp-device-variables>

Note:The OIDs above have a trailing ".0" to specify their full OID.

Calculation Variables

A Calculation type variable receives the result of an arithmetic expression. After all variables have been polled, InterMapper calculates the expression, and sets the value of its variable to the result. In the example above:

SineValue, (10*sin(0.01*time())), CALCULATION, "10 * sin(0.01 * time())"

The variable "SineValue" will be set to the value of the expression (10 * sin(0.01 * time()). This gives a sine wave that makes an attractive chartable value. Use "$SineValue" to refer to the variable elsewhere in the probe.

Macros

InterMapper supports several macros that show information about a variable:

• ${variablename} or $variablename In a <snmp-device-display> section of a probe file, an occurrence of a variable name (with or without the curly braces ({...}) will be replaced with its value, rounded to the nearest integer. For example, if a calculation variable has the value of 3.14159265, using it in the <display-output> section will result in the value of "3"; if the variable had the value 4.75 it would be displayed as "5". This value will be chartable, that is, clicking it will make a new strip chart, or dragging it will add it to an existing chart. The ipForwDatagrams variable defined above could be referred to in either of these forms:
  

  ${ipForwDatagrams} or $ipForwDatagrams

  
  

• ${chartable: xxx : yyy}In a <snmp-device-display> section of a probe file, the ${chartable: ...} macro controls the number of decimal places. There are two parameters: a formatting string that indicates the number and placement of the digits near the decimal point, and the variable to be formatted. For example, if $var is 3.14159265:
  

  ${chartable: #.## : $var } --> 3.14 ${chartable: #.####### : $var } --> 3.1415927

  
  

• ${variablename:legend}In a <snmp-device-display> section of a probe file, the ${variablename:legend} is replaced with the legend field defined for that variable in the <snmp-device-variables> section. For example:
  

  ${ipForwDatagrams:legend}

  
  would result in the string "Forwarded datagrams".

Enumerated Values

Many MIBs use an integer to represent one of several states. For example, ifOperStatus (1.3.6.1.2.1.2.2.1.8.x) is defined in MIB-II as:

INTEGER { up(1), down(2), testing(3) }

This means that the value 1 represents the "up" condition; 2 represents "down"; and 3 represents "testing".

If you define a variable to retrieve this value as INTEGER or DEFAULT, the probe will display the value as a number. If you define it as a STRING, the probe will use the MIB to find the string representation, and will set the variable to the value "up", "down", or "testing".

If the OID or MIB name isn't defined (because the corresponding MIB hasn't been imported or because of a typo), the probe will display the integer value.