|
|
[ Bottom of Page | Previous Page | Next Page | Contents | Index ]
The following section lists the rule language predicates in alphabetical order.
This predicate is typically used to keep a count of duplicate events that are received. As they are received the repeat_count attribute of the original event is updated with this predicate and the duplicate event is dropped.
The following example shows how events for printer problems are managed:
If a duplicate is not found, the newly received event is processed as usual and added to the event cache.
rule: printer_problem:(
event: _event of_class
within ['Printer_Paper_Out',
'Printer_Toner_Low',
'Printer_Offline',
'Printer_Output_Full',
'Printer_Paper_Jam',
'Printer_Door_Open'],
reception_action:
(
first_duplicate( _event,
event: _printer_ev
where [
status: outside ['CLOSED']
],
_event - 600 - 600
),
commit_rule,
add_to_repeat_count(_printer_ev, 1),
drop_received_event
)
).
all_clear_targets(_clear_event, _target_event)
--OR--
all_clear_targets(_clear_event, _target_event, time_before, time_after)
This predicate is used to search the event cache for all of the events that _clear_event clears. Each found event is returned in _target_event.
If the time_before and time_after arguments are not specified, the event cache search time window takes the default value of 2 years (1 year before and 1 year after). You should limit a time window to the smallest reasonable window whenever possible for better performance.
The following example searches the event cache for all events that are cleared by the event under analysis. As each event is found, it is closed. This rule triggers on the base event, so every incoming leaf event is tested.
rule: 'clear_target_events':(
event: _clr_ev of_class 'EVENT',
action: 'search_for_target':(
all_clear_targets(__clr_ev, _tgt, 3600, 0),
set_event_status(_tgt, 'CLOSED')
)
).
all_duplicates(_event, event: _duplicate where attribute_conditions)
--OR--
all_duplicates (_event, event: _duplicate where attribute_conditions, _referenceEvent -time_before -time_after)
The rule engine does not explicitly provide a loop structure. However, the all_duplicates predicate returns multiple solutions one at a time. When the rule engine runs the all_duplicates predicate, it analyzes all solutions individually and runs the remaining sequence of predicates in the action for each solution.
No class specification is required, since duplicate events are the same class as the event under analysis. For additional information about duplicate events, see What is a duplicate event?.
The following example shows a rule that:
rule: dup_nfs_not_resp:(
event: _event of_class 'OV_NODE_DOWN'
where [severity: _severity],
action: dup_event_severity:(
all_duplicates(_event, event: _dup_OV_ev
where [status: outside ['CLOSED'] ],
_event -300 -300
),
set_event_severity(_dup_OV_ev, _severity)
)
).
all_instances(_event, event: _eventInstance of_class class where attribute_conditions)
--OR--
all_instances(_event, event: _eventInstance of_class class where attribute_conditions, _referenceEvent -time_before -time_after)
The rule engine does not explicitly provide a loop structure. However, the all_instances predicate returns multiple solutions one at a time. When the rule engine runs the all_instances predicate, it analyzes all solutions individually and runs the remaining sequence of predicates in the action for each solution.
The following example action closes all NFS_SERVER_NOT_RESPONDING events whose server attribute has a value of Pascal:
action: (
all_instances(_event, event:_nfs_ev of_class
'NFS_SERVER_NOT_RESPONDING'
where [server: equals 'Pascal' ]),
set_event_status (nfs_ev, 'CLOSED')
)
any_clear_target(_clear_event, _target_event)
--OR--
any_clear_target(_clear_event, _target_event, time_before, time_after)
This predicate is used to search the event cache for the first event that _clear_event clears. The found event is returned in _target_event.
If the time_before and time_after arguments are not specified, the event cache search time window defaults to two years (one year before and one year after). For performance reasons, you should limit a time window to the smallest reasonable window whenever possible.
The following example searches the event cache for the first event found that is cleared by the event under analysis. If an event is found, it is closed.
rule: 'clear_target_event':(
event: _clr_ev of_class 'EVENT',
action: 'search_for_target':(
any_clear_target(_clr_ev, _tgt, 3600, 0),
set_event_status(_tgt, 'CLOSED')
)
).
any_clearing_event(_event, _clear_event)
--OR--
any_clearing_event(_event, _clear_event, time_before, time_after)
This predicate is used to search the event cache for the first clearing event that can be found for _event.
If the time_before and time_after arguments are not specified, the event cache search time window defaults to 2 years (1 year before and 1 year after). You should limit a time window to the smallest reasonable window whenever possible for better performance.
The following example searches the event cache for the first event found that clears the event under analysis. If a clearing event is found, the event under analysis is closed and processing is finished. This rule triggers on the base event, so every incoming leaf event is tested.
rule: 'check_for_clear':(
event: _ev of_class 'EVENT',
action: 'search_for_clear':(
any_clearing_event(_ev, _clr, 3600, 0),
set_event_status(_ev, 'CLOSED'),
commit_set
)
).
attr_condition([classes], [attribute_conditions])
This predicate is used to define attribute conditions for some of the problem events in an event sequence. It must be called from the event_details argument of the create_event_sequence predicate. (The attribute_conditions argument of the create_event_sequence predicate defines attribute conditions for all events in an event sequence.)
Attribute conditions for clearing events are defined with the clears predicate.
See the attribute_conditions argument description for the create_event_criteria for additional details about specifying attribute conditions for this argument, as the syntax is the same.
The following example shows the event sequence for events sent from two monitoring sources: American Power Conversion (APC) uninterruptible power supply and IBM Tivoli Distributed Monitoring. APC events use the hostname attribute to identify affected components. Tivoli Distributed Monitoring uses the probe_arg attribute of the universal_host event to identify affected components.
The attr_condition predicate defines the attribute conditions that must be met by the universal_host event to be eligible for correlation (in this case the severity attribute must equal a value of FATAL).
The attr_exception predicate shows how to do the attribute mapping so the events in the sequence from the two different sources can be correlated.
create_event_sequence(
['upsOnBattery',
'lowBattery',
'upsDischarged',
'universal_host'],
['hostname', ['status','outside',['CLOSED']]
[
clears('powerRestored',[ ], ['upsOnBattery'],[ ]),
clears('returnFromLowBattery',[ ], ['lowBattery'],[ ]),
clears('dischargeCleared',[ ],['upsDischarged'],[ ]),
clears('universal_host',
[ ['severity', equals,'HARMLESS'] ]
['universal_host'],
[ ]),
attr_condition('universal_host',
['severity',equals,'FATAL']),
attr_exception('hostname','universal_host',
'probe_arg')
]
),
attr_exception(attribute, [classes], exception_attribute)
This predicate is used to define attribute conditions for other problem events in an event sequence when the attributes do not match up between the events. It must be called from the event_details argument of the create_event_sequence predicate.
For example, suppose a monitoring system generates its events with the name of affected machines in the hostname attribute. Suppose a different monitoring system assigns the names of affected machines in the probe_arg attribute. In order to correlate these two events based on machine name, you must map the two different attributes to each other using the attr_exception predicate.
Multiple attribute exceptions for an event sequence must be defined with multiple attr_exception predicates.
The following example shows the event sequence for events sent from two monitoring sources: APC uninterruptible power supply and Tivoli Distributed Monitoring. APC events use the hostname attribute to identify affected components. Tivoli Distributed Monitoring uses the probe_arg attribute of the universal_host event to identify affected components. The attr_exception predicate shows how to do the mapping so events are correlated.
create_event_sequence(['upsOnBattery', 'lowBattery',
'upsDischarged', 'universal_host'],
['hostname', ['status', 'outside',
['CLOSED']],
[attr_exception('hostname',
'universal_host',
'probe_arg')]
)
attr_sequence(class, attribute=[value_sequence])
This predicate is used for event classes in an event sequence whose names remain the same but use an attribute value to indicate a status change. It must be called from the event_details argument of the create_event_sequence predicate. It defines the sequence of changed values that the attribute can have as it progresses along an event sequence from left to right.
The following example shows an event sequence for Compaq physical drive events. These events are all of the same class (cpqTape3PhDrvStatusChange). The cpqTapePhyDrvCondition attribute value changes to indicate status, with a value of OK signifying a clearing event.
To accommodate this implementation of one event class with a changing attribute value for all of the events in an event sequence, the attribute and sequence of values (in event sequence order from left to right) must be defined with an attr_sequence predicate.
create_event_sequence(
['cpqTape3PhyDrvStatusChange'],
['hostname', ['status', 'outside', ['CLOSED']]]
[attr_sequence(
'cpqTape3PhyDrvStatusChange',
'cpqTapePhyDrvCondition'=['Degraded', 'Failed'])
]
)
bo_add_at_slotval_begin(_event, _attribute, _value)
This predicate adds the value _value at the beginning of the list of values for attribute _attribute in event _event. This predicate is applicable only if the data type of _attribute is a list.
The following example adds a value to the beginning of the acl attribute. This example assumes the event under analysis is an instance of the Su_Success class.
rule: baroc_example: (
event: _event of_class _class,
% _class is unified with Su_Success.
action: (
% Before the call, the 'acl' attribute contains
% [admin].
bo_add_at_slotval_begin(_event, 'acl','user')
% Now the 'acl' attribute contains [user,admin].
)
).
None.
bo_add_at_slotval_end(_event, _attribute, _value)
This predicate adds the value _value at the end of the list of values for attribute _attribute in event _event. This predicate is applicable only if the data type of _attribute is a list.
The following example rule adds a value to the end of the acl attribute. This example assumes the event under analysis is an instance of the Su_Success class.
rule: baroc_example: (
event: _event of_class _class,
% _class is unified with Su_Success.
action: (
% Before the call, the 'acl' attribute contains
% [admin].
bo_add_at_slotval_end(_event, 'acl','senior')
% Now the 'acl' attribute contains [admin,senior].
)
).
None.
bo_get_class_of(_event, _classname)
This predicate retrieves in _classname the name of the class that _event is an instance of. If _classname is instantiated, the predicate only succeeds when the value corresponds to the class name of the event.
The following example shows how to get the class name of the event under analysis. This example assumes the event under analysis is an instance of the Su_Success class.
rule: baroc_example: (
event: _event of_class _class,
% _class is unified with Su_Success.
action: (
bo_get_class_of(_event, _classname)
% _classname is unified with 'Su_Success'.
)
).
None.
bo_get_class_slots(_classname, _attributes)
This predicate retrieves in _attributes the list of attributes and their definitions for class _classname. The list includes all attributes known to the class; that is, all the attributes defined for the class, as well as any attributes that are inherited from any superclasses.
For each attribute, the following information is provided:
slot(attribute_name,complex_type, element_type,parse_setting,dup_detect_setting,'')
The following example shows how to get a list containing the attribute definitions for the class of the event under analysis. This example assumes the event under analysis is an instance of the Su_Success class.
rule: baroc_example: (
event: _event of_class _class,
% _class is unified with Su_Success.
action: (
bo_get_class_slots(_class, _slots)
)
).
The following list is unified with _attributes for this example. The last piece of information for each attribute is empty and reserved for future IBM use.
[slot(server_handle,SINGLE,INTEGER,NO,NO,''), slot(date_reception,SINGLE,INT32,NO,NO,''), slot(event_handle,SINGLE,INTEGER,NO,NO,''), slot(source,SINGLE,STRING,YES,NO,''), slot(sub_source,SINGLE,STRING,YES,NO,''), slot(origin,SINGLE,STRING,YES,NO,''), slot(sub_origin,SINGLE,STRING,YES,NO,''), slot(hostname,SINGLE,STRING,YES,NO,''), slot(fqhostname,SINGLE,STRING,YES,NO,''), slot(adapter_host,SINGLE,STRING,YES,NO,''), slot(date,SINGLE,STRING,YES,NO,''), slot(status,SINGLE,STATUS,YES,NO,''), slot(administrator,SINGLE,STRING,NO,NO,''), slot(acl,LIST_OF,STRING,NO,NO,''), slot(credibility,SINGLE,INTEGER,NO,NO,''), slot(severity,SINGLE,SEVERITY,YES,NO,''), slot(msg,SINGLE,STRING,YES,NO,''), slot(msg_catalog,SINGLE,STRING,YES,NO,''), slot(msg_index,SINGLE,INTEGER,YES,NO,''), slot(duration,SINGLE,INTEGER,NO,NO,''), slot(num_actions,SINGLE,INTEGER,NO,NO,''), slot(repeat_count,SINGLE,INTEGER,YES,NO,''), slot(cause_date_reception,SINGLE,INT32,NO,NO,''), slot(cause_event_handle,SINGLE,INTEGER,NO,NO,''), slot(pid,SINGLE,STRING,YES,NO,''), slot(from_user,SINGLE,STRING,YES,YES,''), slot(to_user,SINGLE,STRING,YES,YES,''), slot(on_tty,SINGLE,STRING,YES,YES,'')].
None.
bo_get_enum_options(_enumname, _options)
Unifies a list of the string values that are part of the enumeration _enumname with list _options.
The following example gets a list of all valid values for the SEVERITY enumeration for the event under analysis. This example assumes the event under analysis is an instance of the Su_Success class.
rule: baroc_example: (
event: _event of_class _class,
% _class is unified with Su_Success.
action: (
bo_get_enum_options('SEVERITY', _options)
% _options is unified with [UNKNOWN,
% HARMLESS,WARNING,MINOR,CRITICAL,FATAL]
)
).
None.
bo_get_slotval(_event, _attribute, _value)
This predicate gets the value of attribute _attribute in event _event. The value is unified with _value. The value of _value must have the correct type for _attribute for the predicate to succeed.
The following example gets the value of the sub_source attribute from the event under analysis. This example assumes the event under analysis is an instance of the Su_Success class.
rule: baroc_example: (
event: _event of_class _class,
% _class is unified with Su_Success.
action: (
bo_get_slotval(_event, 'sub_source',_sub_source)
% _sub_source is unified with 'su'.
)
).
bo_is_defined_for_class(_attribute, _classname)
This predicate succeeds if attribute _attribute is defined in class _classname.
The following example determines if there is an attribute named pid defined for the event under analysis. This example assumes the event under analysis is an instance of the Su_Success class.
rule: baroc_example: (
event: _event of_class _class,
% _class is unified with Su_Success.
action: (
bo_is_defined_for_class('pid', _class)
% Succeeds.
)
).
None.
bo_is_direct_super_of(_super_classname, _classname)
Succeeds if _super_classname is a direct superclass of _classname.
The following example determines whether the event under analysis is a direct subclass of the Logfile_Su class. This example assumes the event under analysis is an instance of the Su_Success class.
rule: baroc_example: (
event: _event of_class _class,
% _class is unified with Su_Success.
action: (
bo_is_direct_super_of('Logfile_Su', _class)
% This predicate succeeds because
% 'Logfile_Su' is a
% direct superclass of 'Su_Success'.
)
).
None.
bo_is_super_of(_super_classname, _classname)
This predicate succeeds if _super_classname is either a direct or indirect superclass of _classname.
The following example determines whether the event under analysis is a subclass of the Logfile_Base class. This example assumes the event under analysis is an instance of the Su_Success class.
rule: baroc_example: (
event: _event of_class _class,
% _class is unified with Su_Success.
action: (
bo_is_super_of('Logfile_Base', _class)
% _class was instantiated to 'Su_Success'
% in event filter.
% This predicate succeeds because
% 'Logfile_Base' is a superclass
% of 'Su_Success'.
)
).
None.
bo_remove_from_slotval(_event, _attribute, _value)
This predicate removes the value _value from the list of values for attribute _attribute in event _event. This predicate is applicable only if the data type of _attribute is a list.
The following example removes a value from the acl attribute. This example assumes the event under analysis is an instance of the Su_Success class.
rule: baroc_example: (
event: _event of_class _class,
% _class is unified with Su_Success.
action: (
% Before the call, the 'acl' attribute contains [admin].
bo_add_at_slotval_end(_event, 'acl','senior'),
% Now the 'acl' attribute contains [admin,senior].
bo_add_at_slotval_begin(_event, 'acl','user'),
% Now the 'acl' attribute contains [user,admin,senior].
bo_remove_from_slotval(_event, 'acl',
'admin')
% Now the 'acl' attribute contains [user,senior].
)
).
None.
bo_reset_default_slotval(_event, _attribute)
This predicate instantiates the default value to attribute _attribute of event _event.
The following example shows a use of the predicate. This example assumes the event under analysis is an instance of the Su_Success class.
rule: baroc_example: (
event: _event of_class _class,
action: (
bo_reset_default_slotval(_event, 'sub_source')
% The slot 'sub_source' for the event
% under analysis is set back to 'su'.
)
).
None.
bo_set_slotval(_event, _attribute, _value)
This predicate updates the value of attribute _attribute in event _event with value _value.
Unlike the place_change_request predicate, change rules are not evaluated in response to this action.
Also, unlike place_change_request, bo_set_slotval will not automatically update the attribute value in the event database or the event consoles. Often these are updated automatically as part of other rule base activity, such as when the event is initially processed or during a change rule on that event. However, if you are using bo_set_slotval from a change rule on a different event than the current event, the update will not happen. To ensure the attribute is updated everywhere, follow this up with a call to the re_mark_as_modified predicate.
The following example shows how to update the hostname attribute of the event under analysis to the value myhost:
bo_set_slotval(_event, hostname, 'myhost')
cancel_all_timers(_event)
This predicate cancels all timers that were set on an event.
The following example cancels all timers that were set on an event when a more causal event is received. This example assumes some other rule not shown set the timers when the events were received.
rule: cancel_timers:(
event: _ev of_class 'EVENT',
action: cancel_timers:(
first_effect_event(_ev, _effect, 300, 300),
link_effect_to_cause(_effect, _ev),
cancel_all_timers(_effect)
)
).
cancel_timer(_event, _timer_duration, _timer_info)
This predicate cancels a timer that was set on an event based on any or all of its arguments. The _event argument should be specified whenever possible, though. Arguments not specified must be represented in the call by a variable that is not instantiated or by the Prolog anonymous variable (an underscore character). Variables not instantiated in the call are unified with the corresponding values of the cancelled timer.
The following example performs event correlation and sets a timer for 5 minutes before a trouble ticket is created for an event. The 5 minute delay is intended to provide enough time for any related cause events to arrive so that the trouble ticket is hopefully created for a root cause event rather than a related effect event.
When an event is received, the event cache is searched for related events that have been received within the past 5 minutes. (Related events were defined with the create_event_sequence predicate.) If it's determined that the event under analysis is an effect event of a known cause event found in the cache, it is linked to the cause event and rule processing exits. If a related event is not found for the event under analysis, a timer is set for 5 minutes (to see if related cause events come in) and processing exits.
If a related cause event is received within the 5 minute timer window, the existing timer is canceled, the effect event is linked to the cause event, a new timer is set on the event under analysis, and processing exits.
The create_trouble_ticket rule creates a trouble ticket when the timer expires. This example assumes that the operator has created the appropriate script for their trouble ticketing system in scripts/create_trouble_ticket.sh.
rule: set_timer_delay:(
event: _ev of_class 'EVENT',
action: perform_correlation:(
first_related_event(_ev, _related, _type, 300, 300),
(
_type == 'c',
link_effect_to_cause(_ev, _related),
commit_set
;
cancel_timer(_related, 300, _info),
link_effect_to_cause(_related, _ev)
)
),
action: set_timer:(
set_timer(_ev, 300, 0),
commit_set
)
).
timer_rule: create_trouble_ticket:(
event: _ev of_class 'EVENT',
timer_duration: equals 300,
action: create_ticket:(
exec_program(_ev, 'scripts/create_trouble_ticket.sh', '%ld',
[_ev], no)
)
).
change_event_administrator(_event, new_administrator)
This predicate places an internal request to change the administrator attribute of the specified event. This causes the change rules to evaluate the requested change before it is actually applied.
The following example shows how to change the administrator attribute of the event under analysis to bjones:
change_event_administrator(_event, bjones)
change_event_severity(_event, new_severity)
This predicate places an internal request to change the severity attribute of the specified event. This causes the change rules to evaluate the requested change before it is actually applied.
The following example shows how to change the severity attribute of the event under analysis to CRITICAL:
change_event_severity(_event, 'CRITICAL')
change_event_status(_event, new_status)
This predicate places an internal request to change the status attribute of the specified event. This causes the change rules to evaluate the requested change before it is actually applied.
The following example shows how to change the status attribute of the event under analysis to ACK:
change_event_status(_event, 'ACK')
check_all_thresholds(_referenceEvent, _name, _count)
This predicate applies criteria to events in the event cache to determine if any threshold has been exceeded. It succeeds once for each threshold that is exceeded. The name of each threshold and the number of events that matched each threshold that is exceeded are unified with the _name and _count arguments, respectively.
The following example queries the event cache for exceeded thresholds whenever an NT_Performance_Alert event is received:
check_all_thresholds('NT_Performance_Alert', _name,
_count)
check_and_increment_count(_key1, _key2, _max_count, _cur_count)
This predicate first increments a counter and then compares the count to the _max_count argument. If the count is less than _max_count, the predicate succeeds and the count is unified with _cur_count. If the values are equal or the count is greater than _max_count, the predicate fails and _cur_count is not instantiated.
Counters are used to keep track of any arbitrary numeric value. The values of _key1 and _key2 can be set to easily identify the information being recorded. For example:
If the event server stops, all counters are discarded.
The following example counts the number of paper jams on a set of printers, based on receiving an event class of Printer_Jam. Printer counters are identified using a failure,component scheme. Printer_Jam events identify each printer in the hostname attribute.
Each counter is created and initialized the first time the check_and_increment_count predicate is called for a particular printer. Each subsequent call for a particular printer increments its count and then compares it to the threshold value.
An administrator is notified when the number of paper jams on a printer reaches 5, and then the count for that printer is reset to 0 using the init_count predicate. The administrator notification and reset of a count is done in an ELSE clause of a Prolog statement because the check_and_increment_count predicate behavior is failure when the count matches the threshold value.
rule: printer_jam: (
event : _ev of_class 'Printer_Jam'
where [hostname: _hn within ['flr4rm23',
'flr3rm12',
'flr1rm11',
'flr6rm9'
],
action: check_count: (
(check_and_increment_count(printer_jam,_hn,5,_count)
;
% ELSE clause follows
exec_program(_ev,'scripts/notify.sh',
'Printer failure on %s', [_hn], no),
init_count(paper_jam,_hn,0)
)
)
).
check_event_criteria(criteria_name, event)
--OR--
check_event_criteria(criteria_names_list, operator, event)
This predicate applies an event criteria created with the create_event_criteria predicate to an event. If the criteria matches, the predicate succeeds.
The second form of the predicate lets you specify multiple event criteria to an event instance.
rule: filter_event: (
event: _event of_class _class where [ ],
reception_action: check_criteria: (
check_event_criteria([harmless_heartbeat,
harmless_maintenance
],
any,
_event
),
drop_received_event,
commit_rule
)
).check_event_criteria('db_critical', _ev)check_threshold(threshold_criteria_name, _referenceEvent, _count)
This predicate applies criteria to events in the event cache to determine if a threshold has been exceeded. The following algorithm is used:
The not operator can be used to reverse the test to check if a threshold was not exceeded.
The first part of the following example shows how to define threshold criteria with the create_threshold predicate. Its characteristics are:
The second part of the following example shows how to check threshold criteria with the predicate using the criteria defined in the first part. If 3 events that match the search criteria defined in db_critical_search are found within a 10 minute window of the reception time of the reference event _event, the check_hold predicate succeeds and will not succeed again for at least another 5 minutes.
create_threshold('db_critical_threshold',
'db_critical_search',
600,
3,
300)
% Define the threshold criteria.
check_threshold('db_critical_threshold',
_event,
_count)
% Apply the threshold criteria to received event.
clear_closed_events
This predicate removes closed events from the event cache.
None.
The following example prints the contents of the event cache before and after clearing closed events:
print_cache('/tmp/before'),
clear_closed_events,
print_cache('/tmp/after')
None.
clears(class, [attribute_conditions], [target_events], [target_attribute_conditions])
--OR--
clears(class, [attribute_conditions], [target_events], [target_attribute_conditions], [attribute_exceptions])
--OR--
clears(class, [attribute_conditions], [target_events], [target_attribute_conditions], create_reverse_lookup)
--OR--
clears(class, [attribute_conditions], [target_events], [target_attribute_conditions], [attribute_exceptions], create_reverse_lookup)
This predicate is used to define a clearing event for one or more events in a sequence and specify which events it clears. It must be called from within the event_details argument of the create_event_sequence predicate.
If the target attribute conditions are already defined with the attribute_conditions argument of the create_event_sequence predicate, the target_attribute_conditions argument should be an the empty list.
See the attribute_conditions argument description for the create_event_criteria for additional details about specifying attribute conditions for this argument, as the syntax is the same.
The following example creates an event sequence for Compaq physical drive events. These events are all of the same class (cpqTape3PhDrvStatusChange). The cpqTapePhyDrvCondition attribute value changes to indicate status, with a value of OK signifying a clearing event.
The clears predicate defines clearing events as class cpqTape3PhyDrvStatusChange with attribute cpqTapePhyDrvCondition set to a value of OK.
create_event_sequence(
['cpqTape3PhyDrvStatusChange'],
['hostname', ['status','outside',['CLOSED']]]
[
attr_sequence(
'cpqTape3PhyDrvStatusChange',
'cpqTapePhyDrvCondition'=['Degraded','Failed']),
clears(
'cpqTape3PhyDrvStatusChange',
[ ['cpqTapePhyDrvCondition',equals,'OK'] ],
['cpqTape3PhyDrvStatusChange'],
[ ])
]
),
commit_action
This predicate prevents analysis of any further solutions for previous predicates in the current rule action and prevents the execution of any further actions in the current rule.
None.
The following example shows that the use of the all_instances predicate might have multiple solutions, but only the first solution is used to perform the action. Any actions that follow in the current rule are not performed; however, other rules and rule sets will still evaluate the event under analysis.
reception_action: action1:
(
all_instances( _event,
event: _dup_down_ev
where [
status: outside ['CLOSED']
],
_event - 600 - 600
),
add_to_repeat_count(_dup_down_ev, 1),
drop_received_event,
commit_action
),
None.
commit_rule
This predicate prevents analysis of any further solutions for previous predicates in the current rule action and prevents the execution of any further actions in the current rule. Additionally, it prevents analysis of any following rules in the current rule set for the event under analysis.
None.
The following example shows that the all_instances predicate might have multiple solutions, but only the first solution is used to perform the rule action. Any actions that follow in the current rule are not performed and any rules that follow the current rule in the current rule set will not evaluate the event under analysis; however, rules in subsequent rule sets will evaluate the event under analysis.
reception_action:
(
all_instances( _event,
event: _dup_toner_ev
where [
status: outside ['CLOSED']
],
_event - 600 - 600
),
add_to_repeat_count(_dup_toner_ev, 1),
drop_received_event,
commit_rule
),
None.
commit_set
This predicate prevents the following:
None.
The following example shows that the all_instances predicate might have multiple solutions, but only the first solution is used to perform the rule action. Any actions that follow in the current rule are not performed and any rules that follow the current rule in the entire rule base will not evaluate the event under analysis.
reception_action:
(
all_instances( _event,
event: _dupper
where [
status: outside ['CLOSED']
]),
drop_received_event,
add_to_repeat_count(_dupper, 1),
commit_set
),
None.
convert_ascii_time(_time_structure, _time_string)
This predicate converts a time structure to an atom representing the time. _time_structure must be instantiated before calling convert_ascii_time. _time_string must be free.
The following example shows how to get the current time structure from the local system, convert the time structure to a string, and update the time_string attribute of the event with the string.
get_local_time(_time_local_struct), convert_ascii_time(_time_local_struct, _time_string), bo_set_slotval(_event, time_string, _time_string)
convert_gm_time(_time_epoch, _time_gm_struct)
This predicate converts an epoch time number to a time structure in GMT. _time_epoch must be instantiated before calling convert_gm_time. _time_gm_struct must be free.
The following example shows how to:
The time_epoch attribute could then be used for comparisons and the time_string attribute could be used for viewing by a person.
get_time(_time_epoch), bo_set_slotval(_event, time_epoch, _time_epoch), convert_gm_time(_time_epoch, _time_gm_struct), convert_ascii_time(_time_gm_struct, _time_string), bo_set_slotval(_event, time_string, _time_string)
convert_local_time(_time_epoch, _time_local_struct)
This predicate converts an epoch time number to a time structure in local system time. _time_epoch must be instantiated before calling convert_local_time. _time_local_struct must be free.
The following example shows how to:
The time_epoch attribute could then be used for comparisons and the time_string attribute could be used for viewing by a person.
get_time(_time_epoch), bo_set_slotval(_event, time_epoch, _time_epoch), convert_local_time(_time_epoch, _time_local_struct), convert_ascii_time(_time_local_struct, _time_string), bo_set_slotval(_event, time_string, _time_string)
create_cache_search_criteria(search_name, criteria_name, attributes, dup_detect)
--OR--
create_cache_search_criteria(search_name, criteria_name, attributes, dup_detect, returnOrder)
This predicate defines named searches for querying the event cache. It is used in conjunction with:
The second form of the predicate lets you specify a logical order for returning events when multiple events were defined in the event criteria. For example, if order was not defined and the event classes were specified in the event criteria as [A,B,C,D,E], the events found in the cache would be returned as they were located during the search; that is, if a C event was found first because it was the most recent, it would be returned first, if an E event was then found, it would be returned next, and so forth. If you specified to return the events in order, all class A events would be returned as they were found, then all class B events would be returned as they were found, and so forth. Specifying order of return can make it easier for you to develop rules that identify the root cause of a problem.
This predicate should be run in a rule triggered by a TEC_Start event at event server start-up time. This loads the named search once, instead of every time it is needed.
The following example creates a search named db_critical_search, which uses the event criteria named db_critical. This search finds any event that passes the db_critical event criteria and whose hostname attribute is the same value as the reference event. The return_order argument has been omitted and therefore defaults to random, meaning events in the list are returned in the order found during the search.
create_cache_search_criteria('db_critical_search',
'db_critical',
['hostname'],
yes
)
create_clearing_event(class, [attribute_conditions], [target_events], [target_attribute_conditions])
--OR--
create_clearing_event(class, [attribute_conditions], [target_events], [target_attribute_conditions], [attribute_exceptions])
--OR--
create_clearing_event(class, [attribute_conditions], [target_events], [target_attribute_conditions], create_reverse_lookup)
--OR--
create_clearing_event(class, [attribute_conditions], [target_events], [target_attribute_conditions], [attribute_exceptions], create_reverse_lookup)
This predicate is typically used to define a clearing event for one or more problem events that are not part of an event sequence.
This predicate can be used to define any clearing event, even if the events it clears are specified in one or more event sequences.
Under typical circumstances, you only need to specify absolute conditions. Attribute-match conditions are evaluated only in the extremely rare case of when clearing events have been received before problem events arrive and a reverse lookup is needed for correlation.
See the attribute_conditions argument description for the create_event_criteria for additional details about specifying attribute conditions for this argument, as the syntax is the same.
Other monitoring systems might send events containing the name of an affected machine in the hostname attribute. To correlate these events based on machine names, map the two attributes to each other using the attribute_exceptions argument.
The attr_exception rule language predicate is used to defined the attribute_exceptions argument. See attr_exception for additional details.
create_clearing_event('CiscoLinkUp',
[ ],
['CiscoLinkDown'],
['origin'],
no)The event class of the clearing event is also specified in the target_events argument because this clearing event clears events of the same class but with a different attribute value.
create_clearing_event( 'cpqDa3PhyDrvStatusChange', [ ['cpqDaPhyDrvStatus',equals,'OK'] ], ['cpqDa3PhyDrvStatusChange'], ['hostname',['cpqDaPhyDrvStatus',not_equals,'OK'] ], no),
create_event_criteria(criteria_name, class, fire_on_non_leaf, attribute_conditions)
This predicate defines criteria used for determining the state of an event. Criteria are used where needed in any rule action by the check_event_criteria predicate, and are also used by the create_cache_search_criteria predicate.
This predicate should be run in a rule triggered by a TEC_Start event at event server start-up. This loads the criteria once, instead of every time it is needed.
The following checks are done at runtime to this predicate. Errors can be obtained with the log_error predicate, which is described on page log_error.
[['attribute', operator, 'value'], ['attribute, operator, 'value']]
| Simple Type | Operator |
|---|---|
| ENUM, INTEGER, REAL | equals greater_than greater_than_equal less_than less_than_equal not_equals outside within |
| STRING | equals not_equals matches outside within |
The order of event classes in the list is significant if you use the return_order argument with a value of order in the create_cache_search_criteria predicate when defining a search using this event criteria. See the create_cache_search_criteria for additional information.
create_event_criteria(example_criteria, 'TEC_DB', no, [['hostname', equals, 'chair' ], ['hostname', not_equals, 'chair1' ], ['hostname', matches, 'ch.*r' ], ['repeat_count', within, [5]], ['repeat_count', outside, [10,15]], ['repeat_count', equals, 5], ['repeat_count', not_equals, 6], ['repeat_count', greater_than, 4], ['repeat_count', greater_than_equal, 5], ['repeat_count', less_than, 6], ['repeat_count', less_than_equal, 5], ['severity', within, ['MINOR']], ['severity', outside, ['FATAL','HARMLESS']], ['severity', equals, 'MINOR'], ['severity', not_equals, 'FATAL'], ['severity', greater_than, 'HARMLESS'], ['severity', greater_than_equal, 'MINOR'], ['severity', less_than, 'CRITICAL'], ['severity', less_than_equal, 'CRITICAL'] ] ),
create_event_criteria('db_critical',
'TEC_DB'
yes,
[['hostname',matches,
'DB_SRV*'],
['severity',
greater_than_equal,
'CRITICAL']
]
)create_event_criteria('ups_problem',
['upsOnBattery',
'upsBatteryLow',
'upsBatteryDischarged'],
yes,
[['hostname',equals,'homer']]
)create_event_sequence([event_sequence], [attribute_conditions])
--OR--
create_event_sequence([event_sequence], [attribute_conditions], [event_details])
This predicate is used to define a sequence of events, and any additional information pertaining to those events, that make up an event sequence. An event sequence is a series of events (generally causally related) that occur in a fixed order.
This information is loaded into the knowledge base of the rule engine at event server start-up and is used by rules that call correlation predicates. You can load it with a rule triggered by a TEC_Start event at event server start-up time.
See the attribute_conditions argument description for the create_event_criteria for additional details about specifying attribute conditions for this argument, as the syntax is the same.
Predicate |
Description |
|---|---|
| attr_condition | Defines absolute attribute conditions for a single event in an event sequence. |
| attr_exception | Defines an attribute that must match a different attribute in other events in an event sequence. |
| attr_sequence | Defines the values of an attribute that change due to a problem event's position in an event sequence. |
| clears | Defines a clearing event for events in an event sequence. |
The problem events are specified in event-sequence order, from left to right, the root cause being the upsOnBattery event. The last event in the sequence (universal_host) is generated by Tivoli Distributed Monitoring. Each of the problem events in the sequence has a related clearing event defined with the clears predicate. The uninterruptible power supply events are related if the hostname attributes have the same value.
The Tivoli Distributed Monitoring universal_host event is handled a little differently because the value for the affected host is stored in the probe_arg attribute (rather than the hostname attribute like the uninterruptible power supply events). This requires mapping of the probe_arg attribute to the hostname attribute of the uninterruptible power supply events so correct comparisons can be made. A situation like this is referred to as an attribute exception and requires the use of the attr_exception predicate, which is called from the event_details argument of the create_event_sequence predicate.
A universal_host event with a severity of FATAL is generated when a host is unavailable. When the host is available again, the same event is sent with a severity of HARMLESS. This situation means that two events of the same class are differentiated by the value of an attribute. This requires the use of the attr_condition predicate in the event_details argument of the create_event_sequence predicate to define that a universal_host event is only to be correlated with an uninterruptible power supply event if its severity is FATAL. Furthermore, a universal_host event is a clearing event only of its severity is HARMLESS.
The attribute_conditions argument for the first three clears predicates in the example are empty lists because the clearing events are event classes and attribute conditions are not needed. Their hostname attributes must match because hostname is specified in the attribute_conditions argument for the create_event_sequence predicate.
The attribute_conditions argument for the fourth clears predicate places a condition on the universal_host event's severity attribute for the value being equal to HARMLESS for defining a clearing event. The specification of the hostname attribute in the attribute_conditions argument for the create_event_sequence predicate and the attr_exception predicate called from the event_details argument of the create_event_sequence predicate ensure that the host names match between clearing and problem events.
create_event_sequence(
['upsOnBattery',
'lowBattery',
'upsDischarged',
'universal_host'],
['hostname', ['status','outside',['CLOSED']]
[
clears('powerRestored',[ ], ['upsOnBattery'],[ ]),
clears('returnFromLowBattery',[ ],['lowBattery'],
[ ]),
clears('dischargeCleared',[ ],['upsDischarged'],
[ ]),
clears('universal_host',
[ ['severity', equals,'HARMLESS'] ]
['universal_host'],
[ ]),
attr_condition('universal_host',
['severity',equals,'FATAL']),
attr_exception('hostname','universal_host',
'probe_arg')
]
),This monitor generates events of the same class, using the cpqTapePhyDrvCondition attribute to indicate status. This attribute with a value of OK designates a clearing event. To handle this type of event sequence, the attribute name and the sequence of values (in event-sequence order from left to right) it can assume must be defined with the attr_sequence predicate, which is called from the event_details argument of the create_event_sequence predicate.
The event_sequence argument only defines one class because this one event comprises the entire event sequence. Status is dependent upon the cpqTapePhyDrvCondition attribute.
In the clears predicate, a target_attribute_conditions argument is not needed because the conditions for the problem events are already defined with the attr_sequence predicate.
create_event_sequence(
['cpqTape3PhyDrvStatusChange'],
['hostname', ['status','outside',['CLOSED']]]
[
attr_sequence(
'cpqTape3PhyDrvStatusChange',
'cpqTapePhyDrvCondition'=['Degraded','Failed']),
clears(
'cpqTape3PhyDrvStatusChange',
[ ['cpqTapePhyDrvCondition',equals,'OK'] ],
['cpqTape3PhyDrvStatusChange'],
[ ])
]
),
The create_event_sequence predicate can be used to define this type of event sequence by specifying one complete sequence with subsequent sequences that include at least one of the events that all of the related sequences have in common.
If a sub-sequence branches from the complete sequence and then reconnects later in the sequence, both the event where it branched and the event where it reconnected must be specified. You should specify the complete sequence first and then specify sub-sequences that branch from or connect to it; this approach will make it easier for you to write the predicates.
The following two create_event_sequence predicates completely define the event sequence shown in the flowchart for this example. The cpqHe3ThermalTempDegraded event in the second predicate specifies that the cpqHe3ThermalCpuFanFailed event joins the sequence defined in the first predicate.
create_event_sequence(
['cpqHe3ThermalSystemFanDegraded',
'cpqHe3ThermalSystemFanFailed'
'cpqHe3ThermalTempDegraded',
'cpqHe3ThermalTempFailed'],
[hostname, ['status', equals, 'OPEN']],
[
clears('cpqHe3ThermalSystemFanOK',
[ ],
['cpqHe3ThermalSystemFanDegraded],
[ ]),
clears('cpqHe3ThermalTempOK',
[ ],
['cpqHe3ThermalTempDegraded],
[ ]),
clears('cpqHe3ThermalConfirmation',
[ ],
['cpqHe3ThermalTempFailed],
[ ])
]
),
create_event_sequence(
['cpqHe3ThermalCpuFanFailed',
'cpqHe3ThermalTempDegraded'],
[hostname, ['status', equals, 'OPEN']],
[
clears('cpqHe3ThermalCpuFanOK',
[ ],
['cpqHe3ThermalSystemFanFailed],
[ ])
]
),None.
create_threshold(threshold_criteria_name, cache_search_criteria_name, _window, _count, _max_report_frequency)
This predicate defines the criteria for setting a threshold for events in the event cache. It is used in conjunction with the check_threshold predicate. It should be run in a rule triggered by a TEC_Start event at event server start-up time. This loads the criteria once.
The following example shows how to define threshold criteria with the predicate. Its characteristics are:
create_threshold('db_critical_threshold',
'db_critical_search',
600,
3,
300)
decrement_slot(_event, _attribute_name, _by_value, _trigger)
This predicate subtracts a number from the value of the specified integer attribute.
The following example shows predicate usage:
decrement_slot(_event,host_down,1,no)
drop_change_request
This predicate prevents a change request from being applied after change rules are run.
None.
The following example shows that for a request to change the status of an event to ACK or CLOSED, if the requesting user is not Root-myHost-region, the change request is dropped and the msg attribute of the event is set to a denial message. The change request is not evaluated by any other change rules after being dropped.
change_rule: deny_state_change_of_TTs:(
event: _event of_class _class,
sender: _sender equals operator(_x),
slot: status set_to _new_status within ['ACK', 'CLOSED'],
action: (
_sender \== operator('Root_myHost-region'),
bo_set_slotval(_event,'msg','modification denied !'),
drop_change_request
)
).
None.
drop_received_event
This predicate causes the event under analysis to be discarded after the rules are evaluated with it.
None.
The following example rule shows how to count the number of duplicate NFS_NOT_RESPONDING events that are received and then drop them so they're not stored in the event database. This results in one event kept with its repeat_count attribute updated each time a duplicate is received.
rule: dup_nfs_not_resp:(
event: _event of_class 'NFS_NOT_RESPONDING',
action: dup_and_drop_event:(
first_duplicate(_event,event: _dup_nfs_ev
where [status: outside ['CLOSED'] ]
),
add_to_repeat_count (_dup_nfs_ev, 1),
drop_received_event
)
).
None.
erase_globals(_group)
This predicate removes all the global variables in a group from the knowledge base.
The following example removes all of the global variables in the Maintenance group from the knowledge base:
erase_globals('Maintenance')
None.
exec_program(_event, file_name, _format_string, _arg_list, watch_status)
This predicate launches a program. The program's completion status can be monitored.
For every format specification in the format string, there must be a corresponding element in the argument list. The data types in the format string must be compatible with their corresponding values in the argument list. If there are no format specifications in the format string, the argument list must be an empty list, written as [ ]. The length of a formatted command line is limited to 256 characters.
The following example shows a use of the predicate:
exec_program(_event,
% Pass in the event pointer for access to
% its environment variables.
'scripts/send_notice',
% Program path/name.
'-m "%s" -s %s',
% Format string.
[_msg, _severity],
% Argument list.
'YES')
% Watch status.
)
The %s format specifiers of the _format_string argument are bound to the msg and severity attributes of the event. The send_notice program is launched with four command line arguments, such as shown in following example:
send_notice -m "Su to root failed for Joe" -s CRITICAL
Note that double quotation marks are used to delimit the value of the msg attribute so it is presented as a single argument to the send_notice command.
exec_program_local(_name, _event, file_name, format_string, _arg_list, watch_status)
This predicate launches a program asynchronously on the local event server (local means the server where the rule engine is installed). When the program finishes, a TASK_COMPLETE event is generated if the watch_status argument is set to 'YES'. This event contains details about the program's execution. The TASK_COMPLETE event class is defined in the tec.baroc file. A description of its attributes are as follows:
Usually a pair of rules are created when using this predicate. The first rule launches the program. The second rule evaluates the results of the program when it is done and might take some action depending on the results.
For every format specification in the format string, there must be a corresponding element in the argument list. The data types in the format string must be compatible with their corresponding values in the argument list. If there are no % format specifications in the format string, the argument list must be an empty list, written as [ ]. The length of a formatted command line is limited to 256 characters.
The following example shows:
rule: program_start: (
event: _event of_class 'TEC_DB'
where [ ],
reception_action: start_it: (
exec_program_local('lst_tmpdir',_event,'ls /tmp',
'',[ ],'YES')
)
).
rule: program_result: (
event: _event of_class 'TASK_COMPLETE'
where [task_name: _task_name equals 'lst_tmpdir',
% Test for program name. If passed, assign
% value to variable.
task_number: _task_num
% Assign task_number attribute value to
% variable.
],
reception_action: process_program_result: (
bo_get_slotval(_event,execution_msg,_results),
% Get value of execution_msg attribute and assign to
% variable. Attribute is a list type.
member(_result_line,_results),
(_result_line == 'OK' ->
% Test each element for OK value.
ok
% OK value found in list. Run ok predicate.
; % Else.
do_not_ok_thing
% OK value not found in list. Run not_ok
% predicate.)
)
).
exec_task(_event, task_name, format_string, _arg_list, watch_status)
This predicate launches a task from a task library. The task's completion status can be monitored. Tasks provided by the Tivoli Enterprise Console product are described in the IBM Tivoli Enterprise Console Command and Task Reference.
For every format specification in the format string, there must be a corresponding element in the argument list. The data types in the format string must be compatible with their corresponding values in the argument list. If there are no format specifications in the format string, the argument list must be an empty list, written as [ ]. The length of a formatted command line is limited to 256 characters.
-l tasklibname -h hostname -a arg1 -a arg2...The example in exec_program shows the use of format strings.
exec_task(_event, 'Send_Email', '-l "T/EC Tasks" -h "stumpy" -a "%s" -a "%s"', ['joe@company.com', 'joe@company.com'], 'NO')
wruntask -t Send_Email -l "T/EC Tasks" -h "stumpy" -E -a "joe@company" -a "joe@company"
rule: plain_rule1_42: (
description:'ADSM incremental backup task',
event: _ev1 of_class within [
'MSSQLDatabase_LogSpacePercentUsedDB']
where [severity: _ev1_severity
collection: _ev1_collection,
hostname: _ev1_hostname
] ,
reception_action: action0: (
(exec_task(_ev1,
'ADSMIncBackup',
'-l MSSQLManagerTasks -h \'@%s:%s\'',
[_ev1_collection,_ev1_hostname],
'YES'
)
)
)
).
The exec_task call resolves to the following command when an event is received for an MSSQLDatabase collection on host master@holon@holon:
wruntask -t ADSMIncBackup -l MSSQLManagerTasks \ -h @MSSQLDatabase:master@holon@holon -E
exec_task_local(_name, _event, file_name, format_string, _arg_list, watch_status)
This predicate launches a task asynchronously from a task library on the local server (local means the event server where the rule engine is installed). Tasks provided by the Tivoli Enterprise Console product are described in the IBM Tivoli Enterprise Console Command and Task Reference.
When the program finishes, a TASK_COMPLETE event is generated if the watch_status argument is set to 'YES'. This event contains details about the task's execution. The TASK_COMPLETE event class is defined in the root.baroc file. A description of its attributes are as follows:
Usually a pair of rules are created when using this predicate. The first rule launches the task. The second rule evaluates the results of the task when it is done and might take some action depending on the results.
For every format specification in the format string, there must be a corresponding element in the argument list. The data types in the format string must be compatible with their corresponding values in the argument list. If there are no format specifications in the format string, the argument list must be an empty list, written as [ ]. The length of a formatted command line is limited to 256 characters.
-l tasklibname -h hostname -a arg1 -a arg2...
The example exec_program shows the use of format strings.
The following example shows:
rule: task_start: (
event: _event of_class 'TEC_DB'
where [ ],
reception_action: start_it: (
exec_task_local(
'send_dbadmin,
_event,
'Send_Email',
'-l "T/EC Tasks" -h "stumpy" -a "%s"
-a "%s"',
['joe@company.com','joe@company.com'],
'YES'
)
)
).
rule: task_result: (
event: _event of_class 'TASK_COMPLETE'
where [task_name: _task_name equals 'send_dbadmin',
% Test task name. Assign task_name value to
% variable if passed.
task_number: _task_num
% Assign task_number attribute value to
% variable.
],
reception_action: process_task_result: (
bo_get_slotval(_event,execution_msg,_results),
% Get value of execution_msg attribute and assign to
% variable. Attribute is a list type.
member(_result_line,_results),
(_result_line == 'OK' ->
% Test each element for OK value.
ok
% OK value found in list. Run ok predicate.
; % Else.
do_not_ok_thing
% OK value not found in list. Run not_ok
% predicate.)
)
).
first_causal_event(_effect_event, _cause_event)
--OR--
first_causal_event(_effect_event, _cause_event, time_before, time_after)
This predicate is used to search the event cache for the root cause event in an event sequence defined with the create_event_sequence predicate. The event must also meet the criteria defined with the create_event_sequence predicate. For example, if events A, B, C, and D are defined as an event sequence in that order, and event D is event under analysis, this predicate will return the most recent instance of event A if it exists and meets the defined criteria, otherwise return event B if it exists, otherwise return event C if it exists, otherwise it fails.
If the time_before and time_after arguments are not specified, the event cache search time window defaults to 2 years (1 year before and 1 year after). You should limit a time window to the smallest reasonable window whenever possible for better performance.
The following example searches the event cache for a related cause event that has been previously received. If one is found, the effect event is acknowledged and linked to the cause event. This rule triggers on a superclass but it searches for a cause event. This design lets you create a single rule to process any number of events that are related.
rule: 'link_effect_to_cause':(
event: _effect of_class 'EVENT',
action: 'search_for_cause':(
first_causal_event(_effect, _cause, 3600, 0),
set_event_status(_effect, 'ACK'),
link_effect_to_cause(_effect, _cause)
)
).
first_duplicate(_event, event: _duplicate where attribute_conditions)
--OR--
first_duplicate(_event, event:_duplicate where attribute_conditions, _referenceEvent -time_before -time_after)
No class specification is required, since the duplicate events are always of the same class. For additional information about duplicate events, see What is a duplicate event?.
If the -time_before and -time_after arguments are not specified, the event cache search time window defaults to 2 years (1 year before and 1 year after). You should limit a time window to the smallest reasonable window whenever possible for better performance.
The following example rule shows how to count the number of duplicate NFS_NOT_RESPONDING events that are received and then drop them so they're not stored in the event database. This results in one event kept with its repeat_count attribute updated each time a duplicate is received.
Note that this example doesn't specify a time window argument, thus defaulting to a 2 year window (1 year before and 1 year after). You should limit a time window to the smallest reasonable window whenever possible for better performance.
rule: dup_nfs_not_resp:(
event: _event of_class 'NFS_NOT_RESPONDING',
action: dup_and_drop_event:(
first_duplicate(_event,event: _dup_nfs_ev
where [status: outside ['CLOSED'] ]
),
add_to_repeat_count (_dup_nfs_ev, 1),
drop_received_event
)
).
first_effect_event(_cause_event, _effect_event)
--OR--
first_effect_event(_cause_event, _effect_event, time_before, time_after)
This predicate is used to search the event cache for the effect event related to a cause event in an event sequence defined with the create_event_sequence predicate.
If the time_before and time_after arguments are not specified, the event cache search time window defaults to 2 years (1 year before and 1 year after). You should limit a time window to the smallest reasonable window whenever possible for better performance.
The following example searches the event cache for a related effect event that has been previously received. If one is found, the effect event is acknowledged and linked to its related cause event. This rule triggers on a superclass but it searches for a related effect event. This design lets you create a single rule to process any number of events that are related.
rule: 'link_cause_to_effect':(
event: _cause of_class 'EVENT',
action: 'search_for_effect':(
first_effect_event(_cause, _effect, 3600, 0),
set_event_status(_effect, 'ACK'),
link_effect_to_cause(_effect, _cause)
)
).
first_instance(event: _event of_class class where attribute_conditions)
--OR--
first_instance(event: _event of_class class where attribute_conditions, _referenceEvent -time_before -time_after)
Succeeds once for the first event that satisfies the specified class, attribute, and time window conditions.
The following example shows a rule that:
rule: escalate: (
description: 'escalate host down events when causing NFS
problems',
event: _event of_class 'NFS_No_Response'
where [ server: _server],
action: 'increase_sev': (
first_instance(event: _down_ev of_class
'universal_host'
where [status: outside ['CLOSED'],
probe_arg: equals _server,
severity: equals 'CRITICAL'],
_event - 600 - 600 ),
set_event_severity(_down_ev, 'FATAL')
)
).
first_related_event(_referenceEvent, _related_event, _relation)
--OR--
first_related_event(_referenceEvent, _related_event, _relation, time_before, time_after)
This predicate is used to search the event cache for the logically earliest cause or effect event related to the reference event. Logically earliest means as defined from left-to-right in an event sequence, with the logically earliest event starting from the left. If the found event is a cause event, the _relation argument is instantiated with the value of c. If the found event is an effect event, the _relation argument is instantiated with a value of e. For example, if events A, B, C, and D are defined with the create_event_sequence predicate as an event sequence in that order and the first_related_event predicate is called with an instance of event C as the reference event, the first instance of event A would be returned with the _relation argument instantiated with a value of c if it exists, otherwise event B would be returned with _relation set to c if it exists, otherwise event D would be returned with _relation set to e if it exists, otherwise the predicate fails.
This predicate should be used whenever correlation is needed to find cause events in the event cache, and then find effect events if a cause event is not found. Because this predicate only performs one search, it is more efficient than using the first_causal_event predicate followed by the first_effect_event predicate sequence of calls.
If the time_before and time_after arguments are not specified, the event cache search time window defaults to 2 years (1 year before and 1 year after). You should limit a time window to the smallest reasonable window whenever possible for better performance.
The following example searches the event cache for the logically earliest event related to the event under analysis. If one is found, the found event is acknowledged and linked to the reference event, either as a cause event or effect event, depending upon the returned value of the relation argument. This rule triggers on a superclass but it searches for a related event. This design lets you create a single rule to process any number of events that are related.
rule: 'link_effect_to_cause':(
event: _ev of_class 'EVENT',
action: 'search_for_cause_or_effect':(
first_related_event(_ev, _related,_relation, 3600,0),
(
_relation == 'c',
set_event_status(_ev, 'ACK'),
link_effect_to_cause(_ev, _related)
;
set_event_status(_related, 'ACK'),
link_effect_to_cause(_related, _ev)
)
)
).
forward_event(_event)
This predicate forwards an event to an event server.
The predicate looks for the event server's location in the tec_forward.conf file (located in the rule_base_dir/TEC_RULES directory). You must edit the tec_forward.conf file and change the value for the ServerLocation option to the host name of the system for the forwarded event.
The default setting in the tec_forward.conf file for the TestMode option is yes. This means that events are forwarded to a file. In order to actually forward an event to an event server, you must delete or comment out the TestMode option in the tec_forward.conf file.
The following example forwards events with a severity of CRITICAL or FATAL to the event server specified in the tec_forward.conf file:
rule: escalate: (
event: _evt of_class within [ 'EVENT' ]
where
[severity: within ['CRITICAL', 'FATAL'],
reception_action: action0:(
forward_event(_evt)
)
).
None.
generate_event(event_class, list_of_event_attributes)
This predicate generates an event internally; that is, from within the event server instead of externally from a source such as an event adapter.
The attributes for the generated event. The attributes must be specified in a list using the following format:
[attribute1=value1, attribute2=value2,...]
The following example generates an event of class TradingDBDown with 4 attributes:
action:(
generate_event('TradingDBDown',
[source='SNMP',
origin=_origin,
hostname=_host,
msg='Trading DB host is down']
)
)
None.
get_attributes(_event, [ attribute_name=_attribute_value, ...] )
This predicate retrieves the values of event attributes and instantiates variables with those values. The second argument is in list format.
The following example retrieves the hostname, severity, and status attribute values from the event under analysis and instantiates them in the _hostname, _severity and _status variables, respectively:
get_attributes(_event,[hostname=_hostname,
severity=_severity,
status=_status
]
)
None.
get_config_param(_name, _variable, default)
This predicate gets a rule engine configuration value defined in the $BINDIR/TME/TEC/.tec_config file and unifies it with a variable.
If the _name argument does not exist in the file, the default argument is unified with the _variable argument.
The following example sets the _tec_rule_host variable to chair. If the tec_rule_host setting did not exist in the file, the variable would have been set to a value of not set. Some .tec_config file entries are shown first.
#.tec_config settings #tec_rule_cache_size=10000 #tec_rule_cache_full_history=86400 #tec_rule_cache_non_closed_history=155520 #tec_rule_cache_clean_freq=3600 tec_rule_trace=YES tec_rule_trace_file=/tmp/rules.trace tec_rule_host=chair tec_server_handle=5
get_config_param(tec_rule_host,_tec_rule_host,'not set')
None.
get_global_grp(_group, _key,_value)
This predicate gets the value of all global variables in a group from the knowledge base. The predicate loops through the variables in the group and instantiates _value for each variable found. _value and _key must be free.
The following example gets all of the global variables for the Maintenance group.
get_global_grp('Maintenance', _key, _value),
get_global_var(_group, _key,_value,_default)
This predicate gets the value of one global variable from the knowledge base and unifies it with _value. If the variable has no value, it is set to _default and _default is unified with _value. _value must be free.
The following example rule:
rule:
check_maint_mode:
(
event: _event of_class _event_class
where [
origin: _origin
],
reception_action:
(
get_global_var('Maintenance', _origin, _maint_mode, 'off'),
_maint_mode == 'on',
drop_received_event,
commit_rule
)
).
get_globals(_group, _key,_value)
This predicate returns the group key, key, and value for each global variable. The arguments must be free. The predicate loops through the global variables and instantiates the three arguments for each global variable found.
The following example shows predicate usage:
get_globals(_group,_key,_value)
get_gm_time(_time_gm_struct)
This predicate gets the current time represented in GMT. _time_gm_struct must be free.
The following example shows how to get the structure for the current time in GMT, convert the time to a string, and update the time_string attribute of the event with the string:
get_gm_time(_time_gm_struct), convert_ascii_time(_time_gm_struct, _time_string), bo_set_slotval(_event, time_string, _time_string)
get_local_time(_time_local_struct)
This predicate gets the current local system time. _time_local_struct must be free.
The following example shows how to get the structure for the current local system time, convert the time to a string, and update the time_string attribute of the event with the string:
get_local_time(_time_local_struct), convert_ascii_time(_time_local_struct, _time_string), bo_set_slotval(_event, time_string, _time_string)
get_time(_time_epoch)
This predicate gets the current time represented by an integer number of seconds since the epoch. _time_epoch must be free.
The following example shows how to get the epoch time number and then update the time_epoch attribute of the event with the number.
get_time(_time_epoch), bo_set_slotval(_event, time_epoch, _time_epoch)
global_exists(_group, _key)
This predicate checks that the global variable in group key _group at key _key exists. If the variable exists, the predicate succeeds.
The following example checks for the global variable whose key is the value of the origin attribute of the event under analysis and belongs to the Maintenance group:
global_exists('Maintenance',_origin)
None.
increment_slot(_event, _attribute_name, _by_value, _trigger)
This predicate adds a number to the value of the specified integer attribute.
The following example shows predicate usage:
increment_slot(_event,host_down,1,no)
init_count(_key1, _key2, _value)
This predicate creates a counter identified by the values of _key1 and _key2. It also initializes the counter to the value of _value. Typically, the initial value is set to 0.
This predicate is used in conjunction with the check_and_increment_count predicate, which is used to increment a count and compare it to a threshold value.
Counters are used to keep track of any arbitrary numeric value. The values of _key1 and _key2 can be set to easily identify the information being recorded. For example:
If the event server stops, all counters are discarded.
The following example counts the number of paper jams on a set of printers, based on receiving an event class of Printer_Jam. Printer counters are identified using a failure,component scheme. Printer_Jam events identify each printer in the hostname attribute.
Each counter is created, initialized to 0, and incremented to 1 the first time the check_and_increment_count predicate is called for a particular printer. Each subsequent call for that printer increments the count and then compares the count to the threshold value.
An administrator is notified when the number of paper jams on a printer reaches 5, and then the counter for that printer is reset to 0 using the init_count predicate. The administrator notification and reset of a counter is done in an ELSE clause of a Prolog statement because the check_and_increment_count predicate behavior is to fail when the count matches the threshold value.
rule: printer_jam: (
event : _ev of_class 'Printer_Jam'
where [hostname: _hn within ['flr4rm23',
'flr3rm12',
'flr1rm11',
'flr6rm9'
],
action: check_count: (
(check_and_increment_count(printer_jam,_hn,5,_count)
;
% ELSE clause follows
exec_program(_ev,'scripts/notify.sh',
'Printer failure on %s', [_hn], no),
init_count(paper_jam,_hn,0)
)
)
).
init_event_activity(_file, _event_ exclusions, _attribute_criteria, _threshold)
This predicate defines the file for the report and defines the criteria for generating the report. An event activity report contains summary counts of the events in the event cache. You can configure the report to exclude particular events, filter on event attributes, and exclude counts that fall below a threshold value.
This predicate should be run in a rule triggered by a TEC_Start event at event server start-up time. This loads the predicate once, instead of every time it is needed.
A list element can be a single attribute or a nested list of multiple attributes; for example, [hostname, severity] can be one element. In the example of the [hostname, severity] nested list, a count of each severity is given for each host.
The class keyword can be used in a nested list to count by event class name. For example, the [class, hostname] nested list provides a count of each host for each event class._rep_freq is 20,
init_event_activity(
'/tmp/event_activity',
% Report file
['TEC_Heartbeat', % Do not report these events
'TEC_Maintenance'
],
[source, % Single attribute reporting
hostname,
severity,
status,
[hostname,severity], % Multiple attribute reporting
[class,hostname] % Class reporting
],
5 % Do not report counts less
%than this
),rule: configure_event_activity: (
event: _event of_class 'TEC_Tick'
where [msg: _msg equals 'Event Activity Report',
duration: _reporting_frequency],
reception_action: start_timer: (
set_timer(_event,_reporting_frequency,_msg),
commit_rule
)
). Event Activity For Server tkennedy
From: Thu Mar 02 14:14:02 2000.
To : Thu Mar 02 14:14:18 2000.
Reporting Frequency: 0 Minutes.
Total Events: 3332
Reporting Threshold: 5
=============================================================
Event Class Summary
=============================================================
Count Class Name
-------------------------------------------------------------
849 TEC_Tick
848 TEC_DB
822 TEC_Notice
812 TEC_Error
=============================================================
Slot Summary
=============================================================
Count Slot Criteria
-------------------------------------------------------------
3332 status=OPEN
590 severity=MINOR
574 severity=WARNING
564 severity=CRITICAL
550 severity=UNKNOWN
544 severity=HARMLESS
510 severity=FATAL
12 hostname=midnight.austin.lab.tivoli.com
12 source=69.1.3.30
11 hostname=dhcp12-235.austin.lab.tivoli.com
11 source=69.1.12.235
11 hostname=stingray.austin.lab.tivoli.com
11 source=69.1.5.82
10 hostname=austin.lab.tivoli.com
10 source=69.1.1.6ip_node_unreachable(_ipaddress, _event)
This predicate tests to see if the given IP address is contained in the cache the event server maintains of unreachable IP addresses. If _ipaddress matches the subnet address and subnet mask of any of the subnets contained in the cache, the _event argument is set to the event handle for the corresponding TEC_ITS_SUBNET_STATUS event.
This event can then be used to correlate the current event to the corresponding TEC_ITS_SUBNET event by using the link_effect_to_cause predicate. To check the success of the correlation, test that the the _event argument is unified with an existing event, by using ground(_event). If it succeeds, there is a valid correlation.
This predicate requires that the NetView component be installed and that the netview.rls rule set is active.
is_clearing_event(_event)
This predicate is used to test whether a rule or rule action should be run. If the event has been defined as a clearing event with the create_clearing_event or create_event_sequence predicate, and meets all of the appropriate conditions of the definition, the is_clearing_event predicate succeeds.
The following example rule fragment tests whether the event under analysis is a clearing event. If the test passes, processing would continue with the next statement in the action. This rule triggers on the base event, so every incoming leaf event is tested.
rule: 'process_clearing_events':(
event: _ev of_class 'EVENT',
reception_action: 'check_for_clear':(
is_clearing_event(_ev),
...
link_effect_to_cause(_effect_event, _cause_event)
This predicate updates the cause_date_reception and cause_event_handle attributes of the effect event so that these attributes contain a reference to the cause event. The value of the date_reception attribute of the cause event is placed in cause_date_reception attribute and the value of event_handle attribute of the cause event is placed in the cause_event_handle attribute.
The following example links a universal_oserv event to a universal_host event if they are related, determined by their probe_arg attribute values. If they are related, the status attribute for the universal_oserv event is set to ACK.
rule: link_oserv_to_host: (
event: _event of_class 'universal_oserv'
where [probe_arg: _probe_arg,
severity: equals 'WARNING'
],
action: 'link_host': (
first_instance(event: _host_ev of_class
'universal_host'
where [severity: within ['CRITICAL','FATAL'],
probe_arg: equals _probe_arg,
status: outside ['CLOSED']
]),
set_event_status(_event,'ACK'),
link_effect_to_cause(_event, _host_ev)
)
).
load_globals(_file)
This predicate loads all the global variables from a file into the knowledge base.
The following example shows predicate usage:
load_globals('/tmp/globalvars.txt')
log_error(format_string, variable_list, severity)
This predicate should be run from within a predicate you've created to help you debug rules. The more recent rule language predicates provided by IBM have this predicate embedded within them to help you debug problems with rules.
This predicate provides error messages the following ways:
Before calling the log_error predicate, do the following setup tasks:
tell_err('filename')You can supply more detailed conversion specifications between the % sign and the conversion character, as follows:
The following example shows a user-defined predicate named my_predicate that receives an argument (_data) that is actually passed in to be the argument of a user-defined predicate named check_data. The check_data predicate is the predicate to be debugged. The logic is as follows:
Additionally when the check_data predicate fails, a TEC_Error event is sent to the event server with a severity of CRITICAL, the Bad Data message, and the my_predicate source identifier. The message and the source identifier are assigned to the msg attribute of the event.
my_predicate(_data):-
set_log_error_source(my_predicate),
(
trace_it(check_data),
process_data(_data)
;
log_error('Bad Data %s',[_data],'CRITICAL')
)
place_change_request(_event, _attributename, _newattributevalue)
Change rules are triggered in response to the requested change. If there are no change rules in the rule base, the bo_set_slotval predicate would be a more efficient choice to change an attribute value, because processing resources are not used to check the rule base for change rules.
The following example requests to change the hostname attribute to a value of myhost:
place_change_request(_event, hostname, myhost)
print_cache(file_name)
--OR--
print_cache(file_name, event:_event of_class class where attribute_conditions)
This predicate writes the event cache to a file. Two forms are provided:
print_cache('/tmp/cache/')rule: print_cache: (
event: _event of_class _class,
reception_action: (
print_cache('/tmp/cache', event: _cached_event of_class 'TEC_Start')
)
).rule: print_cache: (
event: _event of_class _class,
reception_action: (
print_cache('/tmp/cache',
event: _cached_event of_class _cached_class where
[status: equals 'CLOSED'])
)
).print_class_tree(_file, _class)
This predicate formats and writes an event class hierarchy tree from the active rule base to a file, starting from a specified class as the root and continuing down to the leaf classes. It also prints the maximum depth and the total width of the tree, which is a representation of the general size of the tree.
The following example formats and writes the entire event class tree of the active rule base (because the starting point is the base event class EVENT) to the /tmp/class_tree file.
print_class_tree('/tmp/class_tree', 'EVENT')
print_event_activity
This predicate writes the event activity report using the criteria set in the init_event_activity predicate. It is usually run from within a timer rule.
The frequency of when to write the report is controlled with the _duration argument of the set_timer predicate.
None.
rule: configure_event_activity: (
event: _event of_class 'TEC_Tick'
where [msg: _msg equals 'Event Activity Report',
duration: _rep_freq],
reception_action: start_timer: (
set_timer(_event,_rep_freq,_msg),
commit_rule
)
).timer_rule: print_and_reset_event_activity: (
event: _event of_class _class
where [ ],
timer_info: equals 'Event Activity Report',
timer_duration: _rep_freq,
action: print_and_reset_event_activity: (
print_event_activity,
reset_event_activity,
set_timer(_event,_rep_freq,
'Event Activity Report')
)
). re_after_match(_name, _string, _result)
This predicate searches for a match in _string using a named regular expression defined with the re_create predicate. The predicate succeeds if a match is found. The substring after the match is returned in _result.
Refer to Perl documentation for information about regular expression syntax and usage.
The following example shows how to use the predicate:
re_create(test,'a.*i') % Create regular expression test. re_after_match(test,'chair',_result) % Search 'chair' using regular expression test. % Return the substring after the match in _result. % Succeeds, 'r' returned in _result.
re_before_match(_name, _string, _result)
This predicate searches for a match in _string using a named regular expression defined with the re_create predicate. The predicate succeeds if a match is found. The substring before the match is returned in _result.
Refer to Perl documentation for information about regular expression syntax and usage.
The following example shows how to use the predicate:
re_create(test,'a.*r') % Create regular expression test. re_before_match(test,'chair',_result) % Search 'chair' using regular expression test. % Return the substring before the match in _result. % Succeeds, 'ch' returned in _result.
re_create(_name, _pattern)
This predicate defines a named regular expression that can be referenced by other regular expression predicates. The predicate fails if the regular expression is not valid. It should be run in a rule triggered by a TEC_Start event at event server start-up time. This loads the predicate once, instead of every time it is needed.
Refer to Perl documentation for information about regular expression syntax and usage.
The following example shows how to define a regular expression and reference it from another regular expression predicate:
re_create(test,'h.*i') % Create regular expression test. re_search_string(test,'chair') % Compare 'chair' to regular expression test. % Succeeds, matches 'hai'.
None.
re_mark_as_modified(_event, _)
This predicate is typically run after using the bo_set_slotval predicate to update event consoles and event database with the latest attribute values for an event.
The following example shows how to update the data for the event pointed to by _oldevent:
re_mark_as_modified(_oldevent, _)
re_match(_name, _string, _index, _result)
This predicate searches for a match in _string using a named regular expression defined with the re_create predicate. The predicate succeeds if a match is found. The matched substring is returned in _result. The _index argument is used to specify which part of the matched substring to return.
Refer to Perl documentation for information about regular expression syntax and usage.
The following example shows how to use the predicate:
re_create(test,'a.*r') % Create regular expression test. re_match(test,'chair',0,_result) % Search 'chair' using regular expression test. % Return the entire result in _result. % Succeeds, 'air' returned in _result.
re_search_string(_name, _string)
This predicate searches for a match in _string using a named regular expression defined with the re_create predicate. The predicate succeeds if a match is found.
Refer to Perl documentation for information about regular expression syntax and usage.
The following example shows how to use the predicate:
re_create(test,'h.*i') % Create regular expression test. re_search_string(test,'chair') % Search 'chair' using regular expression test. % Succeeds, matches 'hai'.
re_send_event_conf(_conf_file, _event)
This predicate sends an event to a remote event server defined in a configuration file. The configuration file must be located in the TEC_RULES subdirectory of the loaded rule base. The predicate references the configuration file by file name only, leaving off the .conf file name extension; for example, with a configuration file named host.conf, specify the value of host for the _conf_file argument. Each time a new configuration file is referenced by the predicate, its name is added to an internal configuration file table and its file handle is kept open. A maximum of 50 concurrent different configuration files are supported.
This predicate supports both connection and connectionless modes of operations. If events are to be forwarded to a remote event server frequently, ensure that the configuration file specifies connection_oriented for the ConnectionMode option. This communication prevents the event server from having to establish a communications channel each time an event is forwarded.
In addition, to ensure that the events intended for a remote event server are separated from events intended for another remote event server, the configuration file must specify the location and name of the cache file for events destined to a remote event server; for example, BufEvtPath=/etc/tivoli/orange.cache.
The following figure shows an example of a configuration file for use with the re_send_event_conf predicate. Configuration file options are described in the IBM Tivoli Enterprise Console Adapters Guide.
ServerLocation=orange.tivoli.com TestMode=no BufEvtPath=/etc/Tivoli/orange.cache # ConnectionMode=connection_oriented
The following example sends the event under analysis to the remote event server specified in the configuration file host.conf:
re_send_event_conf('host', _event)
re_split_event_id(_path_element, _host, _server_handle, _date_reception, _event_handle)
This predicate receives a list element from the server_path attribute as input, parses the element, and unifies (assigns) the parsed values with variables provided as arguments to the predicate. The server_path attribute is a list of elements that provides information about each event server that an event has passed through. Each element contains the information about one event server. The information is for each element is in the format of an event ID, which is described in the section, Event cache. See the IBM Tivoli Enterprise Console Adapters Guide for additional information about the server_path attribute.
The following example iterates through each element in the server_path attribute and parses it:
bo_get_slotval(_event,server_path,_server_path),
% Get the list for the server_path attribute.
member(_item,_server_path),
% Get an element of the list.
% Because _item is free, the list will be traversed
% and each element will be returned in succession.
re_split_event_id(_item,_host,_server_handle,
_date_reception,_event_handle)
% Parse each element into variables.
re_substitute(_name, _string, _substitute, _result)
This predicate searches for a match in _string using a named regular expression defined with the re_create predicate. The predicate succeeds if a match is found. The value in _substitute replaces the match and the new string is returned in _result.
Refer to Perl documentation for information about regular expression syntax and usage.
The following example shows how to use the predicate:
re_create(test,'a.*w') % Create regular expression test. re_substitute(test,'hawk','oo',_result) % Search 'hawk' using regular expression test. % Return the new string in _result. % Succeeds, 'hook' returned in _result.
re_substitute_global(_name, _string, _substitute, _result)
This predicate searches for all matches in _string using a named regular expression defined with the re_create predicate. The predicate succeeds if at least one match is found. The value in _substitute replaces all occurrences of a match and the new string is returned in _result.
Refer to Perl documentation for information about regular expression syntax and usage.
The following example shows how to use the predicate:
re_create(test,'a.*w') % Create regular expression test. re_substitute_global(test,'hawkhawkhawk','oo',_result) % Search 'hawk' using regular expression test. % Return the new string in _result. % Succeeds, 'hookhookhook' returned in _result.
redo_analysis(_event)
When correlating events, it might be necessary to re-evaluate the analysis of a previously received event. This predicate requests that the rule engine redo the analysis of regular rules for the specified event.
The following example places a redo request on previously received INSTALLATION_FAILED events that might have been caused by the disk being full:
rule: disk_full_check_install_failed: (
description: 'look for installationfailed events for this
host',
event: _event of_class 'DISK_FULL'
where [status: equals 'OPEN',
hostname: _hostname ],
action: (
all_instances(event: _install_ev
of_class 'INSTALLATION_FAILED'
where [target_host: equals _hostname],
_event -600 -600 ),
redo_analysis(_install_ev)
)
).
None.
remove_bslashes(_path1, _path2)
This predicate converts the back slashes in the _path1 argument to forward slashes and unifies the new path with the _path2 argument.
The following example converts back slashes in a directory path to forward slashes:
% Assign value. _path="\\tivoli\\data\\repository', % Convert back slashes. % _new_path is unified with /tivoli/data/repository. remove_bslashes(_path,_new_path)
None.
reset_event_activity
This predicate resets the counts for all event reporting criteria to 0. It is usually run from within a timer rule following the print_event_activity predicate.
None.
The following example shows a use of the predicate:
timer_rule: reset_event_activity: (
event: _event of_class _class
where [ ],
timer_info: equals 'Event Activity Report',
timer_duration: _rep_freq,
action: reset_activity: (
print_event_activity,
reset_event_activity,
set_timer(_event,_rep_freq,'Event Activity Report')
)
).
reset_global_grp(_group,_value)
This predicate changes the value of all global variables in a group in the knowledge base. The predicate loops through the variables in the group and for each variable found, changes its value to _value.
The following example resets all of the global variables in the Maintenance group to off.
reset_global_grp('Maintenance', 'off'),
resolve_time(_time_structure, _seconds, _minutes, _hours, _day_of_month, _month, _year, _day_of_week, _day_of_year, _daylight_saving)
This predicate retrieves attributes from a time structure represented by the _time_structure argument, and instantiates the remaining arguments to those attributes. _time_structure must be instantiated before calling resolve_time. The other arguments must be free. The values are in Greenwich mean time (GMT).
You can use this number to determine the type of daylight savings time style used on the current system. This could be useful if you need to manipulate time values returned by this predicate. The following example shows the values from a Solaris system:
#define DST_NONE 0 /* not on dst */
#define DST_USA 1 /* USA style dst */
#define DST_AUST 2 /* Australian style dst */
#define DST_WET 3 /* Western European dst */
#define DST_MET 4 /* Middle European dst */
#define DST_EET 5 /* Eastern European dst */
#define DST_CAN 6 /* Canada */
#define DST_GB 7 /* Great Britain and Eire */
#define DST_RUM 8 /* Rumania */
#define DST_TUR 9 /* Turkey */
#define DST_AUSTALT 10 /* Australian style with
shift in 1986 */
The following example shows how to get the structure for the current local system time, retrieve the attributes of the local system time structure, and update the month attribute of the event with the value of the _month argument.
get_local_time(_time_local_struct),
resolve_time(_time_local_struct, _seconds, _minutes,
_hours,
_day_of_month, _month, _year, _day_of_week,
_day_of_year, _daylight_savings),
bo_set_slotval(_event, month, _month)
save_globals(_file, _group)
This predicate writes all the global variables from a group to a file.
The following example shows how to write the global variables in the Maintenance group to a file:
save_globals('/tmp/globalvars.txt', 'Maintenance')
search_cache(search_name, _referenceEvent, _maxEvents, _foundEvent)
--OR--
search_cache(search_name, _referenceEvent, _timeBefore, _timeAfter, _maxEvents, _foundEvent)
This predicate performs a query of the event cache. It is used in conjunction with the create_cache_search_criteria predicate, which defines a named search.
The second form of the predicate lets you specify a time window with the _timeBefore and _timeAfter arguments.
Succeeds once for each event that satisfies the search criteria.
You can use the get_attributes predicate to get the values for each found event's attributes.
The following example uses the search named db_critical_search to find matching events within a 20 minute time window of the reference event. The search has been instructed to return no more than five matching events.
search_cache('db_critical_search',
_refevent,
600,
600,
5,
_found_event)
set_detailed_debugging(on)
--OR--
set_detailed_debugging(off)
This predicate toggles the writing of rule trace information for predicates that have rule tracing enabled with the trace_it predicate. You can run the set_detailed_debugging predicate from any rule.
The following example shows a user-defined predicate named my_predicate that receives an argument (_data) that is actually passed in as the argument to a user-defined predicate named check_data. The check_data predicate is the predicate to be debugged. The logic is as follows:
Additionally when the check_data predicate fails, a TEC_Error event is sent to the event server with a severity of CRITICAL, the Bad Data message, and the my_predicate source identifier. The message and the source identifier are assigned to the msg attribute of the event.
Regardless of whether the predicate succeeds or fails, trace information is written to the rule trace file.
set_detailed_debugging(on),
my_predicate(_data):-
set_log_error_source(my_predicate),
(
trace_it(check_data),
process_data(_data)
;
log_error('Bad Data %s',[_data],'CRITICAL')
)
None.
set_event_administrator(_event, new_administrator)
This predicate sets the value for the administrator attribute for the specified event.
The following example shows predicate usage:
set_event_administrator(_event, bjones)
set_event_message(_event, _format, [_value])
The format specification is similar to that for the sprintf() function in the C programming language.
You can specify more detailed conversion specifications between the % sign and the conversion character, as follows:
The following example shows various uses of the predicate:
_integer is 123, _real is 12.3, _string = 'Hello, World', % Assign values. set_event_message(_event, '%s', [_string]), % msg attribute assigned 'Hello, World'. set_event_message(_event, '%20s', [_string]), % msg attribute assigned ' Hello, World'. set_event_message(_event, '%-20s', [_string]), % msg attribute assigned 'Hello, World '. set_event_message(_event, 'Integer in decimal notation: %d', [_integer]), % msg attribute assigned 'Integer in decimal % notation: 123'. set_event_message(_event, 'Integer in decimal notation with field width: %10d', [_integer]), % msg attribute assigned 'Integer in decimal % notation with field width: 123' set_event_message(_event, 'Integer in decimal notation with leading zeros: %010d', [_integer]), % msg attribute assigned 'Integer in decimal % notation with leading zeros: 0000000123'. set_event_message(_event, 'Integer in octal notation: %o', [_integer]), % msg attribute assigned 'Integer in octal % notation: 173'. set_event_message(_event, 'Integer in hexadecimal notation: %x', [_integer]), % msg attribute assigned 'Integer in hexadecimal % notation: 7b' set_event_message(_event, 'Real in decimal notation: %f', [_real]), % msg attribute assigned 'Real in decimal % notation: 12.300000'. set_event_message(_event, 'Real in decimal notation with field width: %3.2f', [_real]), % msg attribute assigned 'Real in decimal % notation with field width: 12.30'. set_event_message(_event, 'Real in real notation: %f', [_real]), % msg attribute assigned 'Real in real notation: % 12.300000'. set_event_message(_event, 'Real in exponential notation: %e', [_real]), % msg attribute assigned 'Real in exponential % notation: 1.230000e+01'. set_event_message(_event, 'Real in its shortest form: %g', [_real]) % msg attribute assigned 'Real in its shortest form: 12.3'.
set_event_severity(_event, new_severity)
This predicate sets the severity of the specified event.
The following example shows predicate usage:
set_event_severity(_event, 'CRITICAL')
set_event_status(_event, new_status)
This predicate sets the status attribute of the specified event.
The following example shows how to set the status attribute of the event under analysis to ACK:
set_event_status(_event, 'ACK')
set_global_var(_group, _key,_value)
This predicate sets the value of one global variable in the knowledge base. To set a variable to a list, use the [ ] notation.
The following example shows various uses of the predicate:
set_global_var('My group key', _key, 'My value')
set_global_var('My group key', _key, ['a', 'b', 'c'])
set_global_var('Maintenance', _origin, 'on')
set_log_error_source('source_location')
This predicate defines a source location within a rule action so you have a point of reference from a generated error message to help you debug the rule. For the argument, specify the name of a rule action or other significant identifier (for example, a predicate name).
The following example shows a user-defined predicate named my_predicate that receives an argument (_data) that is actually passed in to be the argument of a user-defined predicate named check_data. The check_data predicate is the predicate to be debugged. The logic is as follows:
Additionally when the check_data predicate fails, a TEC_Error event is sent to the event server with a severity of CRITICAL, the Bad Data message, and the my_predicate source identifier. The message and the source identifier are assigned to the msg attribute of the event.
my_predicate(_data):-
set_log_error_source(my_predicate),
(
trace_it(check_data),
process_data(_data)
;
log_error('Bad Data %s',[_data],'CRITICAL')
)
)
set_timer(_event, timer_duration, timer_info)
This predicate sets a timer on a received event. When the timer expires, the rule engine finishes processing the current event and then triggers timer rules for the specified event. In essence, the expiration of a timer is a transaction requesting the execution of timer rules on a specified event.
The maximum number of active timers that can be placed on events with this predicate is 1000.
An event of class TEC_Tick always exists in the event cache; that is, it is never aged out of the event cache. You can search for this event in the cache and use it to start a timer, knowing that it will always be there.
The first rule in the following example initially sets the timer for event activity report generation. The second rule is evaluated whenever the timer expires for event activity reporting. The action in the second rule prints the event activity report, resets counters for the next event activity report, and sets a new timer for generation of the next event activity report.
rule: (
event: _event of_class 'TEC_Start'
where [ ],
reception_action: (
first_instance(event:_ev of_class 'TEC_Tick' where []),
set_timer(_event, 600, 'Event Activity Report') )
).
timer_rule: reset_print_activity: (
event: _event of_class _class
where [ ],
timer_info: equals 'Event Activity Report',
timer_duration: _rep_freq,
action: reset_print_activity: (
print_event_activity,
reset_event_activity,
set_timer(_event,_rep_freq,'Event Activity Report'
)
).
None.
trace_it(predicate_name)
This predicate designates which user-defined predicates to trace.
The following example shows a user-defined predicate named my_predicate that receives an argument (_data) that is actually passed in to be the argument of a user-defined predicate named check_data. The check_data predicate is the predicate to be debugged. The logic is as follows:
Additionally when the check_data predicate fails, a TEC_Error event is sent to the event server with a severity of CRITICAL, the Bad Data message, and the my_predicate source identifier. The message and the source identifier are assigned to the msg attribute of the event.
my_predicate(_data):-
set_log_error_source(my_predicate),
(
trace_it(check_data),
process_data(_data)
;
log_error('Bad Data %s',[_data],'CRITICAL')
)
)
unlink_from_cause(_effect_event)
This predicate updates the cause_date_reception and cause_event_handle attributes of the effect event to a value of 0, breaking the link between the two events.
The following example shows predicate usage:
unlink_from_cause(_oserv_down_event)
update_event_activity(_event)
This predicate captures information from an event and stores it internally for later reporting. It is typically called in a rule that runs on every event class.
The following example shows a use of the predicate:
rule: update_event_activity: (
event: _event of_class _class
where [ ],
reception_action: update_activity: (
% recorded(event_activity,active),
% Line above used with im.rls (intermediate mgr. rules)
update_event_activity(_event)
)
).
[ Top of Page | Previous Page | Next Page | Contents | Index ]