Netcool/OMNIbus Probe Rules file tips and tricks

Body

1. Netcool/IDE is a very useful GUI rules file editor and debugger

 
Available to download from (MyIBM login required):-
    https://www.ibm.com/software/tivoli/gat/toolsutils
 
The Netcool/IDE provides an IDE for writing/editing rules and allows you to debug and test them using raw capture output of probes, with the ability to set breakpoints, step through statements and see the current values of elements at that point of execution.
 
Another way to help debug rules files, in situ, is to add log statements to output the values of variables at a certain point (which helps confirm any assumptions you are making), i.e.

log( WARNING, "Hit point A in rules, $wibble = ["+$wibble+"]" )
 

2. RawCapture output for unparsed events

 
You can set the RawCapture property dynamically in the rules file to write out the current event into the RawCapture file.

Near the top of the rules file (after the targets, tables and arrays have been defined) set::-

# Turn %RawCapture property off
# Note that this will override setting in the properties file or command line
%RawCapture = 0
...

Then, where you get to a point in the rules that you don't have rules to deal with an event (such as the default: case of the switch($enterprise) in the NcKL rules file):-

switch( $enterprise ) {
...other case statements...
    default:
        log(DEBUG, "<<<<< (snmptrap.rules) Enterprise ID not found in any include file. >>>>>")
        @Summary = "No Rules Found for Enterprise ID: " + $enterprise + " (see details)"
        @Severity = 2
        @Type = 0
        %RawCapture=1
}

3. regmatch() before extract()

 
Always, always, always do this.

# Pull out blah item and store in @AlertKey
# REF: BLAH123
if( regmatch( $foo, "^[A-Z]*[0-9]: Blah-(.*)$" ) )
{
    # Note use of exact same regexp string for both regmatch and extract, including the extraction parentheses - these won't affect regmatch()
    @AlertKey = extract( $foo, "^[A-Z]*[0-9]: Blah-(.*)$" )
} else {
    # Optionally log out an error to say that it wasn't in the right format
    log( ERROR, "BLAH123: Data not in expected format: ["+$foo+"]" )
    # If using Tip #2 about dynamic RawCapture you can even do:-
    %RawCapture=1
}
 

4. Obtaining sub-second timing information in the rules file

 
The rules file language provides no direct call to get sub-second timing information, but you can get it via the updateload() calls and extract it manually.

$timer = "2.2"
$timer = updateload( $timer )
log( DEBUG, "Value: "+$timer )

2011-09-01T12:55:06: Debug: D-UNK-000-000: Value: 2.2 1314878106.64880

Calling updateload() on an 'empty' loadstring (i.e. one with just the window sizes) gives you the result of gettimeofday(), i.e. sec and usec values.

Value: 2.2 1314878106.64880

So the current UTC time is 1314878106 sec and 64880 usec.

Remember to reset $timer = "2.2" before calling again otherwise this initial value is not guaranteed to be updated.
 
You can also use this to time specific operations within the rules file language:-
 
$timer = "2.2"
$timer = updateload( $timer )
$hostname = gethostname( "192.168.1.123" )
$timer = updateload( $timer )
log( ERROR, "Timing="+$timer )
log( ERROR, "Hostname="+$hostname )

2011-10-05T12:51:48: Error: E-UNK-000-000: Timing=2.2 1317815508.849179 127603
2011-10-05T12:51:48: Error: E-UNK-000-000: Hostname=alexsmachine.example.com
 

5. Use regreplace() to help clear up tokens/strings

 
regreplace() provides regular expression matching and substitution, it can be used in a variety of ways:-

a) Remove all occurrences of $, ! or ' in any of the tokens:-

foreach ( x in $* )
{
    $x = regreplace( $x, "[$!']", "" )
}

b) Replace multiple spaces with a single space:-

foreach ( x in $* )
{
    $x = regreplace( $x, " +", " " )

6. update( @SomeField, FALSE ) does not prevent a field from being updated by an ObjectServer trigger (such as the deduplication trigger)

It only cancels a previous:-
    update( @SomeField )
or
    update( @SomeField, TRUE )
that occurred in the rules file.

If the deduplication trigger contains:-
    set old.SomeField = new.SomeField;
then that field will be updated regardless of what you've put in the rules file.

If you want to conditionally update SomeField then don't update it in the deduplication trigger, control it completely in the rules file; or add a flag that can be tested in the trigger to determine whether it should be updated, i.e.

...rules...
@UpdateSomeField=1
...

...deduplication trigger...
    if( new.UpdateSomeField = 1 ) then
        set old.SomeField = new.SomeField;
    end if;
...