Event deduplication

Event deduplication handles situations where the same event may be reported from multiple sources, particularly in highly-available architectures. If multiple Itential Platform instances are listening to events from the same downstream resource, multiple event messages may be broadcast in the Itential Platform event system for a single downstream occurrence. Without deduplication, any actions listening for those events will execute multiple times. In most cases, the desired behavior is to respond only once for each distinct occurrence.

Example: If an NSO instance is observed by a cluster of Itential Platform servers, each server maintains its own individual connection to NSO. NETCONF events produced by NSO are observed by all running Itential Platform instances, resulting in multiple messages being generated for a single NETCONF event. Configuring event deduplication ensures only one message is emitted to the event bus, producing a single response from the system.

Configure event deduplication

Event deduplication is configured in two places: the active Itential Platform profile, and the service config of each event producer that requires deduplication.

The two most important settings are active and uniqueProps. active turns the feature on or off. uniqueProps defines which message properties are used to determine whether two messages are duplicates. For example, if the three fields below (/value/device, /value/event, /value/timestamp) are identical between two events, the second is treated as a duplicate and dropped.

Sample service config:

1
{
2
  "properties": { },
3
  "eventDeduplication": {
4
    "active": true,
5
    "cacheTtl": 100,
6
    "algorithm": "md5",
7
    "uniqueProps": [
8
      "/value/device",
9
      "/value/event",
10
      "/value/timestamp"
11
    ]
12
  }
13
}

eventDeduplication properties

algorithm

The algorithm setting is rarely required. Available options can be discovered via openssl list -digest-algorithms, or openssl list-message-digest-algorithms on older systems. The library used to create a message digest uses the system’s OpenSSL utility.

uniqueProps

uniqueProps tells the deduplication system which fields define a unique message. The specified fields are extracted from the message and hashed to produce a unique identifier.

For example, if uniqueProps specifies device, event, and timestamp, all three of the following messages are considered duplicates of each other — the second and third are dropped, and only the first is emitted:

1
{ "device": "ios1", "event": "CRASH", "timestamp": 1592329817, "remediation": "REBOOT" }
2
{ "device": "ios1", "event": "CRASH", "timestamp": 1592329817 }
3
{ "device": "ios1", "event": "CRASH", "timestamp": 1592329817, "region": "us-east-1" }

When using inclusive configuration (JSON Pointer Array or Inclusive Mask Object), uniqueProps must be specified explicitly. If none of the specified fields are found in a message, it is treated as unique and subsequent similar messages will not be deduplicated.

JSON Pointer Array

When uniqueProps is an array, it must contain a list of JSON Pointer expressions that form an inclusive list of properties to compare:

1
[
2
  "/value/device",
3
  "/value/event",
4
  "/value/timestamp"
5
]

Inclusive Mask Object

uniqueProps can also be specified as an object with true or false leaf values. In this form it acts as a mask. Note that true and false values cannot be mixed in the same mask object.

The following is equivalent to the JSON Pointer Array example above:

1
{
2
  "value": {
3
    "device": true,
4
    "event": true,
5
    "timestamp": true
6
  }
7
}

The inverse is also supported. If the messages contain additional properties like region and severity that should be excluded, the following mask produces the same result as both examples above:

1
{
2
  "value": {
3
    "region": false,
4
    "severity": false
5
  }
6
}

Email event triggers

The email adapter can create duplicate jobs when used as an event trigger in Operations Manager, particularly when emails are processed at a high rate. To resolve this, specify a messageId field in uniqueProps:

1
{
2
  "properties": { },
3
  "eventDeduplication": {
4
    "active": true,
5
    "cacheTtl": 10000,
6
    "algorithm": "md5",
7
    "uniqueProps": [
8
      "/messageId"
9
    ]
10
  }
11
}