...
- an event
name
, which specifies the name of the newly created event, - a list of
events
(more precisely, their names), which are the events to consider for correlation, - a (minimum)
count
of events that have to be detected to trigger the rule, - an optional list of
groupby
clauses, which define whether the count is interpreted globally for all named events, or separately within smaller groups, - optional
delayedaction
andautoacknowledge
clauses, which define how the triggering events should be handled, - an optional
enrich
clause, which adjusts the content of the newly created event, - from version 2.2 .0a onwards, optional
copy_first
,copy_last
,copy_highest
andcopy_groupby
clauses which further control the contents of the newly created event, - from version 2.2 onwards, an optional
inhibit
parameter, which disables correlation temporarily after a rule has fired, - and finally a
window
parameter, which defines the time window to examine.
...
In version 2.2 this limitation has been removed, and much more precise control of the event content is possible.
Content Control Directives (Version 2.2
...
and newer)
When a synthesis rule creates a new event, the following steps are performed:
- If no
copy_first
,copy_last
,copy_highest,
orcopy_present
copy_groupby
directives are present, then a backwards-compatible directive 'copy_last => [ qr// ]'
is added. - (opEvents 2.2 and newer only)
copy_firstpresent
is evaluated first, and . It specifies which event properties should be copied over from the earliest trigger event.
Each listed property is copied over; if the directive contains a regular expression (e.g.qr/cust.*/
, then all properties with names matching the regular expression are copied. copy_last
is checked next, and properties listed here are copied over from the most recent trigger event.
The property copying does overwrite all properties that were set earlier (bycopy_first
).copy_highest
is checked next, and its properties are sourced from the trigger event with the highest priority.
Again overwriting of properties may happen.copy_groupby
controls whether any of the grouping property values should be saved in the new event.
The format is different for this directive: It must be a list of property target names (or the word 'undef'), in the same order as thegroupby
directive.
For each element in thegroupby
list, the value of the grouping property is saved as the target name in the new event, if a target name is available in thecopy_groupby
list.
If nogroupby
is given for this rule, then acopy_groupby
directive has no effect.- Now the
enrich
clause is checked, and each of its property name - value pairs indicates which properties should be set to (or overwritten with) a particular static value. - Now the
node
,stateful
andelement
properties are automatically adjusted if required (see below for details). - Finally, the event name is set to the rule name, certain undesirable properties are removed, an audit trail of triggering events is added (by adding the properties
nodes
andeventids
), the event is marked assynthetic
and is inserted into the database.
Please note that "earliest event" in step 1 refers to the event with the earliest event timestamp, which does not necessarily reflect its processing order. opEvents processes inputs mostly - but not always - in chronological order. If you have multiple 'earliest' events (all with the same timestamp) then their order is undefined and copy_first
will pick a random event.
The same caveat applies in step 2 for the "most recent event".
Automatic Event Node for Synthetic Events
If no copy_*
or enrich
clause has caused the the node
property to be set explicitly, then the global default node is used instead.
'Set explicitly' means a copy_*
or enrich
clause did include the node
property, i.e. not if the node property copying happened because of a regular expression.
The global default node in opEvents 2.2 is configurable using the configuration item opevents_correlation_node
, and it's normally called "global".
This virtual node is automatically (re)created if missing.
This behaviour is different from opEvents before 2.2, where all synthetic events were attached to the last trigger event's node. To emulate the old behaviour you have to change your correlation rules, so that they include the directive
copy_last => [qr//, 'node']
which causes a blanket copy of all properties from the last trigger event and an explicit copy of the node property (to disable the automatic event node choice).
Example Rule
Here is an example rule demonstrating the new directives:
...
- set from their first occurrence.
This rule must contain explicit property names only, i.e. no regular expressions.
opEvents checks all trigger events in chronological order, and when it finds an event that has a value for the desired property, it copies that value over and stops looking for that property. Any later events that might have the property as well do not contribute to the result.
A rule likecopy_present => [ 'alpha', 'beta' ]
will pull thealpha
andbeta
properties from wherever they are present for the first time, but independent of each other: a trigger event can contribute none, either or both properties. copy_first
is evaluated next, and specifies which event properties should be copied over from the earliest trigger event.
Each listed property is copied over; if the directive contains a regular expression (e.g.qr/cust.*/
, then all properties with names matching the regular expression are copied.copy_last
is checked next, and properties listed here are copied over from the most recent trigger event.
The property copying does overwrite all properties that were set earlier (bycopy_first
).copy_highest
is checked next, and its properties are sourced from the trigger event with the highest priority.
Again overwriting of properties may happen.copy_groupby
controls whether any of the grouping property values should be saved in the new event.
The format is different for this directive: It must be a list of property target names (or the word 'undef'), in the same order as thegroupby
directive.
For each element in thegroupby
list, the value of the grouping property is saved as the target name in the new event, if a target name is available in thecopy_groupby
list.
If nogroupby
is given for this rule, then acopy_groupby
directive has no effect.- Now the
enrich
clause is checked, and each of its property name - value pairs indicates which properties should be set to (or overwritten with) a particular static value. - Now the
node
,stateful
andelement
properties are automatically adjusted if required (see below for details). - Finally, the event name is set to the rule name, certain undesirable properties are removed, an audit trail of triggering events is added (by adding the properties
nodes
andeventids
), the event is marked assynthetic
and is inserted into the database.
Please note that "earliest event" in step 2, 3 and 4 refers to the event with the earliest event timestamp, which does not necessarily reflect its processing order. opEvents processes inputs mostly - but not always - in chronological order. If you have multiple 'earliest' events (all with the same timestamp) then their order is undefined and copy_first
will pick a random event. The same caveat applies for the "most recent event".
Automatic Event Node for Synthetic Events
If no copy_*
or enrich
clause has caused the the node
property to be set explicitly, then the global default node is used instead.
'Set explicitly' means a copy_*
or enrich
clause did include the node
property, i.e. not if the node property copying happened because of a regular expression.
The global default node in opEvents 2.2 is configurable using the configuration item opevents_correlation_node
, and it's normally called "global".
This virtual node is automatically (re)created if missing.
This behaviour is different from opEvents before 2.2, where all synthetic events were attached to the last trigger event's node. To emulate the old behaviour you have to change your correlation rules, so that they include the directive
copy_last => [qr//, 'node']
which causes a blanket copy of all properties from the last trigger event and an explicit copy of the node property (to disable the automatic event node choice).
Example Rule
Here is an example rule demonstrating the new directives:
Code Block |
---|
'1' => {
name => "Very Sick Node",
events => [ "Node Down", "SNMP Down", "Interface Down", "Service Down",
"Service Degraded", "Interface Flap", "Node Flap", "WMI Down" ],
window => 120,
count => 3,
groupby => [ 'node.name' ], # we want separate events for each node of course
enrich => { stateful => "Very Sick Node", priority => 5, state => 'down', element => undef }, # new event is stateful only if stateful is set or copied by name
copy_last => [ qr//, 'node' ], # can set from node here (all events share it)
copy_groupby => [ 'node' ], # or from here; must set it explicitely somewhere, or the event goes to opevents_correlation_node
}, |
Stateful Synthetic Events (Version 2.2
...
and newer)
By default, synthetic events are not stateful events, i.e. they are not subject to deduplication and they cannot be acknowledged (or 'closed') by any future 'opposite' event.
...
- Without
inhibit
, after the first 20 events for group A you'll get one synthetic event for group A; another after the next 20 and so on.
For group B, one synthetic event will be generated for the first 20; the remaining 5 are too few to trigger anything. - With
inhibit
set to 40 seconds (for example), you'll get the very first group A synthetic event as before, but then no synthetic events for this rule and group A for the next 40s;
After that correlation for group A resumes 'from scratch' and any events received from then onwards are counted and correlated as normal.
For group B with its fewer triggers the inhibit behaviour doesn't change anything visibly, there's still just one synthetic event.
Note that the inhibit timer for group A is totally independent of any inhibit for group B: inhibit applies to a particular rule and its fullgroupby
contextcounted and correlated as normal.
For group B with its fewer triggers the inhibit behaviour doesn't change anything visibly, there's still just one synthetic event.
Note that the inhibit timer for group A is totally independent of any inhibit for group B: inhibit applies to a particular rule and its fullgroupby
context.
In opEvents version 2.2, the combination of the options autoacknowledge
and inhibit
does not acknowledge trigger events that occur during the inhibit period; only 'successful' triggers are acknowledged. This has been changed for greater consistency and better storm control in versions 2.2.1 and newer, where successful triggers and any trigger events occurring during the inhibit period are also acknowledged automatically.