groupingKey element

Typically, each active rule has one rule instance, or copy, that is running in the Active Correlation Technology engine. However, sometimes the same rule is needed for different groups of events, which are often related to different groups of resources. The grouping key is one or more event attributes, or parts of event attributes, that can be used to separate the selected events into different groups for unique processing as a group. The <groupingKey> element defines the grouping key for a rule. The purpose of the <groupingKey> element is to direct the rule to create a separate rule instance (or copy of itself) for each group of events that share common characteristics (as defined by the values of their attributes that comprise the grouping key).

Details

The following two scenarios illustrate the importance of the grouping key.

Scenario 1:
Two events occur, a DB2down event and a DB2up event. The DB2® program runs on three computers that are named A, B, and C. A sequence rule is defined to correlate a DB2down event with a DB2up event and to alert the operator when the DB2 program stops and does not restart.

If the sequence rule is defined without the grouping key, and a DB2down event is received from computer A, a DB2up event from any of the computers would complete the sequence, but this would not accomplish what was intended. However, if the grouping key were defined as the hostname attribute, a unique copy, or instance, of the rule would be created for each unique value of the hostname attribute in the selected events. The Active Correlation Technology engine would send each event to the correct rule instance (the rule instance for that event's hostname value). Therefore, if a DB2down event is received from computer A, the Active Correlation Technology engine would create a rule instance for computer A. If a DB2down event is received from computer B, the Active Correlation Technology engine would create a second rule instance for computer B. When a DB2up event is received from computer B, the Active Correlation Technology engine processes that event in the second rule instance. The sequence is complete, and the operator is alerted because the DB2down and DB2up events from computer B are correctly correlated.

Scenario 2:
An event for an Incorrect login attempted message occurs on all computers in a particular environment. The event contains a user ID. A threshold rule is defined to issue a warning to the operator if this event occurs more than 10 times in 5 minutes.

A grouping key could be defined as the user ID. Then, a new rule instance would be created for each unique user ID. Each user's login attempts would be tracked in a unique threshold rule instance, with each instance having a separate count of the number of login attempts by that user. The operator would receive a warning if any user ID exceeds 10 incorrect logins in 5 minutes.

Other variations of this idea include:
  • The grouping key could be defined as the host name rather than the user ID. This option could detect a large number of incorrect login attempts on a single computer.
  • The grouping key could be defined as a combination of the host name and user ID. This option could detect a potential hack attempt by a specific user ID against a specific computer.

If the same attribute is in all event types that are specified for a rule, the use of the <attributeName> element is the simplest and most common way to define a grouping key.

Attributes

<groupingKey> has the following attribute:

Table 1. Attributes of the <groupingKey> element
Name Description Data type Required?
missingAttributeHandling Defines the action that the rule must take under either of these conditions:
  • When a selected event has an attribute that participates in the grouping key but the value for that attribute is missing
  • When the expression within the <computedValue> element returns a null value. The rule treats this null value as a missing attribute value.
The valid values for the missingAttributeHandling attribute are:
  • ignoreEvent (the default value), which means that the rule ignores the event and takes no action on it.
  • ignoreAttribute, which means that the rule accepts the event but ignores the attribute with the missing value. The Active Correlation Technology engine then includes a substitute value for the attribute.
xsd:string No

Contained within

<groupingKey> is contained within the following elements:

Contains

<groupingKey> contains the following elements.

Table 2. Elements contained within the <groupingKey> element
Element Required or optional?
<attributeAlias> 1 of these elements is required. Coding more than 1 of these elements is optional. Multiple occurrences of all three elements are allowed. These elements can be coded in any order.
<attributeName>
<computedValue>