To create a poll condition:
Designing and Managing Behavior Models
-
Using Polls - Writing a Poll Condition - The Basic Procedure for Creating a Poll Condition -
The section explains how to use the Poll Condition page in the Poll Definition window to create a poll condition.
Poll Condition tab.The Poll Condition page is displayed.
Base Object drop-down list, select the base object whose attributes you will use in the poll condition.A list of the base object's attributes is displayed in the Attributes list.
Poll Condition text area, and enter the poll condition.You can enter the poll condition by simply typing the condition in this text area. However, you can also use several shortcuts to enter text:
Attribute list. (You must have selected a base object from the Base Object drop-down list while the poll condition editing area was empty.)
See the section Using the Pop-Up Menu for Perl for further information about this pop-up menu.
When you return to the Poll page -- to save your poll -- the poll condition you've constructed appears in the read-only Poll Condition text area.
NerveCenter includes a number of functions that you can use in constructing a poll condition. Several of these functions are designed specifically for use in poll conditions. For example, they enable you to determine the exact number of seconds between polls and to determine the change in the value of a MIB variable between one poll and the next. You can also use the functions DefineTrigger(), FireTrigger(), AssignPropertyGroup(), and in() and a set of string-matching functions. These functions can be used not only in defining poll conditions, but in defining other objects as well.
The functions and variables available to you for use in poll conditions are summarized in a pop-up menu for Perl accessible via a right mouse click from the poll condition editing area in the Poll Condition page of the Poll Definition window. (See the section, Using the Pop-Up Menu for Perl, for more information.)
For detailed information about all of these functions, see the following sections:
The functions discussed below are designed specifically for use in poll conditions.
Syntax: delta(baseObject.attribute)
baseObject.attribute - The name of a MIB variable qualified by the name of its parent object, for example, ifEntry.ifType.
Description: Returns the difference between the value of baseObject.attribute retrieved by the previous poll and that retrieved by the current poll.
Example: This statement fires a trigger if the number of SNMP messages sent to a node without an acceptable community name has increased:
if (delta(snmp.snmpInBadCommunityNames) >= 1) {
FireTrigger("authFail");
}
Description: Returns the number of seconds that elapsed between the previous poll and the current poll.
Example: This statement fires a trigger if the poll detects interface traffic levels exceeding 80 percent of capacity:
if (((delta(ifEntry.ifInOctets) + delta(ifEntry.ifOutOctets))
* 8) / (ifEntry.ifSpeed * elapsed) >= 0.801) {
FireTrigger("highLoad");
}
Description: Returns true if the poll is not able to read the value of the MIB attribute that precedes the function.
Example: This statement fires a trigger if the poll is unable to read the value of system.sysDescr from an agent's MIB:
if (system.sysDescr not_present) {
FireTrigger("noAgent");
}
Description: Returns true if the poll is able to read the value of the MIB attribute that precedes the function.
Example: This statement fires a trigger if the poll is able to read the value of ifInUcastPkts from an agent's MIB.
if (ifEntry.ifInUcastPkts present) {
FireTrigger("gotInUcastPkts");
}
The DefineTrigger() function enables you to create triggers which you can assign to variables and fire using FireTrigger() in NerveCenter Perl expressions. (In the scope of a subroutine, Perl requires you to define a variable before you can use it.)
You can use DefineTrigger() in NerveCenter anywhere that you write Perl expressions (except for Action Router rule conditions):
As with triggers created with FireTrigger(), the triggers you create with DefineTrigger() are available in the trigger lists NerveCenter displays when you are defining alarm transitions, Perl subroutines, and Action Router rule conditions.
The syntax for the DefineTrigger() function is shown below:
DefineTrigger()
name - "The" name of the trigger in quotation marks.
Description: DefineTrigger() creates a trigger which you can assign to a variable and fire using FireTrigger().
Example one: The expression creates a trigger named "hello" which is assigned to a Perl variable "$trig" and is then fired:
$Trig = DefineTrigger("hello")
FireTrigger($trig)
Example two: The following code excerpt is from a Perl subroutine (TestParentSetNode) associated with the downstream alarm suppression behavior models shipped with NerveCenter. $TriggerFlag stores the name of the trigger to be fired which depends on the status of the parent node:
DefineTrigger('UnReachable');
DefineTrigger('Down');
DefineTrigger('Testing');
...
if( ($ParentStatus eq "Down" || $ParentStatus eq "UnReachable") &&
$TriggerFlag eq "NotSet" )
{
$TriggerFlag = "UnReachable";
}
elsif( $ParentStatus eq "Up" )
{
$TriggerFlag = "Down";
}
elsif( $ParentStatus eq "Testing" && $TriggerFlag ne "Down" )
{
$TriggerFlag = "Testing";
}
...
FireTrigger( $TriggerFlag );
The FireTrigger() function enables you to fire a trigger from anywhere in NerveCenter that you write Perl expressions:
You specify the name of the trigger and optionally its subobject attribute and node attribute.
As with triggers created with DefineTrigger(), the triggers you create with FireTrigger() are available in the trigger lists NerveCenter displays when you are defining alarm transitions, Perl subroutines, and Action Router rule conditions.
The syntax for the FireTrigger() function is shown below:
FireTrigger()
Syntax: FireTrigger("name", [subobject, [node]])
name - The name of the trigger in quotation marks. Name can also be a Perl variable that is assigned a trigger using the DefineTrigger() function. For example:
$var=DefineTrigger("myTrigger");
FireTrigger($var);
subobject - You can pass a subobject to FireTrigger() in one of two ways.
You can use a string literal, for example, "ifEntry.2".
Second, if you called FireTrigger() from a trigger function or a Perl subroutine, you can use the function VbObject(n). This function returns the subobject associated with the nth variable binding in a trap or trigger.
node - You can pass a node to FireTrigger in one of three ways.
First, you can use the variable $NodeName, which is the default for this argument. How this variable obtains its value depends on the context in which it is used, as shown in The Value of $NodeName.
Second, include the name of the node in quotation marks, for example, "MyBestRouter" or "192.168.197.110". This string must match the name of the node as it's listed in the NerveCenter Node List window.
Finally, if the node name you want to pass to FireTrigger() is in a trap's or a trigger's variable bindings, you can use the function VbValue(n) to retrieve that name. This function returns the value of the nth variable binding.
Description: FireTrigger() creates a trigger with the name, subobject, and node values that you supply.
Example: The following call generates a trigger with the name "trigger" and the default subobject and node:
FireTrigger("trigger");
You use the AssignPropertyGroup() function to assign a property group to a node. The function can be called from a poll condition, a trap mask trigger function, or a Perl Subroutine alarm action. The node affected is the node being polled, the node from which a trap arrived, or the node associated with the trigger that caused an alarm transition (in the case of a Perl Subroutine action).
The syntax of the AssignPropertyGroup() function is shown below:
Syntax: AssignPropertyGroup("propertyGroup")
propertyGroup - The name of an existing property group.
Description: The function assigns a property group to a node.
Example: The example below shows the AssignPropertyGroup() function being used in a Perl Subroutine alarm action. If the variable $DestStateSev (which holds the name of the NerveCenter severity of the destination state) contains the string "Critical," the property group of the node associated with the trigger that caused the alarm transition is changed to CriticalGrp. The node will now be managed by a new set of behavior models.
if ($DestStateSev eq "Critical") {
AssignPropertyGroup("CriticalGrp")
}
The in() function is available for use in poll conditions, trap mask trigger functions, Perl subroutines, and Action Router rule conditions.
Syntax: in(scalar, scalar, ...)
scalar - An scalar value in a set of scalar values (often integers representing interface types).
Description: Returns true if the value of the attribute that precedes the function is found in the set of scalars in parentheses.
Example: This statement fires a trigger if a particular interface is part of a broadcast network:
if (ifEntry.ifType in (6,7,8,9,11,12,13,15,26,27)) {
FireTrigger("broadcast");
}
NerveCenter provides four string-matching functions (Perl subroutines), which can be used in poll conditions, trap mask trigger functions, OpC trigger functions, Perl subroutines, and Action Router rules. These functions enable you to determine whether a string contains a substring or a word.
Each of the string-matching functions is explained below:
Syntax: CaseContainsString(string, substring)
Description: Returns true if string contains substring. The match is case sensitive.
Syntax: CaseContainsWord(string, word)
Description: Returns true if string contains word, and word begins and ends on a word boundary. The match is case sensitive.
Syntax: ContainsString(string, substring)
Description: Returns true if string contains substring. The match is case insensitive.
Syntax: ContainsWord(string, word)
Description: Returns true if string contains word, and word begins and ends on a word boundary. The match is case insensitive.
There are five different tasks in NerveCenter that require you to write Perl code:
For each of these tasks, you can use not only Perl 5, but some NerveCenter functions and variables that are appropriate to the task. For instance, if you're writing a trap mask trigger function, you can use NerveCenter functions to retrieve information about the variable bindings in the trap that caused the trigger function to be called. You can also use NerveCenter variables that contain information about the contents of the trap.
What functions and variables are available to you depends on the task you're performing. Therefore, NerveCenter provides a pop-up menu in the editing area for each task that indicates which functions and variables are applicable in that situation. Pop-Up Menu for Perl shows the pop-up menu as it appears in the editing area used to create a trap mask trigger function.
The submenu being displayed lists all the variable-binding functions.
Besides serving as documentation, these pop-up menus enable you to enter text in an editing area at the point of the cursor. For example, if you were working in the trigger-function window shown above, selecting the menu entry VbValue would cause the characters "VbValue( " to be written to the editing area.
To make this discussion more concrete, let's look at an example. Let's say that you want to write the following trigger function:
if ($NodeName ne "troublemaker") {
FireTrigger("gotIt");
}
To write this trigger function, you would:
if (.
Trap variables submenu, and select $NodeName from that submenu.
Relational operators submenu, and select ne from that submenu.
"troublemaker") {; then, enter a new line and four spaces.
Other functions submenu, and select FireTrigger from that submenu.
This section presents a number of sample poll conditions and explains how the poll conditions work.
if (system.sysLocation eq "Building 6" and
system.sysObjectID == 1.3.6.1.4.1.9.1) {
AssignPropertyGroup("Cisco6");
}
This poll condition checks to see whether a device is located in Building 6 and whether it is a Cisco product. If the device meets these conditions, it is assigned the property group Cisco6.
if (ifEntry.ifType present and
ifEntry.ifSpeed present and
ifEntry.ifInOctets present and
ifEntry.ifInUcastPkts present and
ifEntry.ifInNUcastPkts present and
ifEntry.ifInDiscards present and
ifEntry.ifInErrors present and
ifEntry.ifOutOctets present and
ifEntry.ifOutUcastPkts present and
ifEntry.ifOutNUcastPkts present and
ifEntry.ifOutDiscards present and
ifEntry.ifOutErrors present) {
FireTrigger("ifData");
}
This poll condition is true as long as the poll is able to read the values of these interface variables from an agent's MIB.
This type of poll condition is useful if you want to gather MIB data that you'll use later in generating a report. For example, if a poll fires an ifData trigger after this poll condition is evaluated, that trigger will contain a list of variable bindings that contains the name and value of each of these attributes. If that trigger causes an alarm transition that has associated with it a Log to File action, these names and values will be written to a log file. That log file can then be used as input to a reporting tool.
if ((delta(ifEntry.ifInErrors) + delta(ifEntry.ifInDiscards) +
delta(ifEntry.ifOutErrors) + delta(ifEntry.ifOutDiscards) - 0.05 *
(delta(ifEntry.ifInErrors) + delta(ifEntry.ifInDiscards) +
delta(ifEntry.ifOutErrors) + delta(ifEntry.ifOutDiscards) +
delta(ifEntry.ifInUcastPkts)+ delta(ifEntry.ifInNUcastPkts) +
delta(ifEntry.ifOutUcastPkts) + delta(ifEntry.ifOutNUcastPkts))
> 0) == 1) {
FireTrigger("highErrorRate");
}
This poll condition is true if the percentage of discarded packets on an interface is greater than five percent during a given polling interval. This is a good example of how to use the delta function.
if (ifEntry.ifType in (37)) {
FireTrigger("typeATM");
}
This poll condition evaluates to true if an interface's ifType attribute equals 37. In other words, the condition is true if the interface is an ATM interface. Obviously, this type of poll condition is useful for classifying interfaces.
if (((delta(ifEntry.ifInOctets) + delta(ifEntry.ifOutOctets) -
0.00125 * elapsed * ifEntry.ifSpeed > 0) &&
(ifEntry.ifType in (6,7,8,9,11,12,13,15,26,27))) == 1 or
((delta( ifEntry.ifInOctets ) + delta(ifEntry.ifOutOctets) -
0.09375 * elapsed * ifEntry.ifSpeed > 0) &&
!( ifEntry.ifType in (6,7,8,9,11,12,13,15,24,26,27))) == 1) {
FireTrigger("highLoad");
}
This poll condition uses the delta, elapsed, and in functions. It determines whether, during the last poll interval, the traffic on an interface on a broadcast network was greater than 1 percent or whether the traffic on an interface on a point-to-point network was greater than 75 percent.
| Writing a Poll Condition | Documenting a Poll |
| 29 July 2003 |