Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Use Correlated Events to Trigger an Event Policy

Configure an event policy to execute when two or more correlated events occur.

Understanding Correlated Events

You can configure an event policy that correlates two or more events. If the events occur as specified, they cause particular actions to be taken. For example, you might want to issue certain operational mode commands when a UI_CONFIGURATION_ERROR event is generated within five minutes (300 seconds) after a UI_COMMIT_PROGRESS event. As another example, you might want to upload a particular file if a DCD_INTERFACE_DOWN event is generated two times within a 60-second interval.

To correlate events in an event policy, include the following statements at the [edit event-options] hierarchy level:

In the events statement, you can list multiple trigger events. For information about defining events in event policies, see Event Policies and Event Notifications Overview. To correlate those events with other events, you configure the within and/or the attributes-match statements.

The within statement defines the correlating events that must (or must not) occur within a specified time interval before a trigger event. The attributes-match statement correlates an event's attribute with another event's attribute or with a regular expression. The event policy executes the actions configured in the then statement only if the specified conditions are met. The following sections discuss how to use the statements.

Correlating Events By Time Interval

You can configure an event policy to execute only if a trigger event occurs within a specified time interval after another event. You do this by configuring the within seconds events statement. The policy is executed if any of the correlating events defined in the within seconds events statement occur within the configured number of seconds before any of the trigger events defined in the first events statement. The number of seconds can be from 60 through 604,800. The not statement causes the policy to execute only if the correlating events do not occur within the configured time interval before a trigger event.

For example, the device executes the following policy if one of the trigger events, event3, event4, or event5, occurs within 60 seconds after one of the correlating events, event1 or event2, occurs:

To configure an event policy to correlate events by time interval:

  1. Configure one or more trigger events.

  2. Configure the correlating events that must or must not occur before a trigger event and within the specified time interval.

    • To specify that a correlating event must occur within the specified time interval before a trigger event, omit the not keyword.

    • To specify that a correlating event must not occur within the specified time interval before a trigger event, include the not keyword.

  3. Configure the actions that the event policy executes if the conditions are met.

Note:

The device executes an event policy if any of the correlating events occur (or do not occur, if you configure the not keyword) before any trigger event. To require that multiple correlating events occur (or do not occur) before a trigger event, configure multiple within statements. Each statement must specify a different time interval.

The within statement also supports executing an event policy when the triggering event occurs a certain number of times within a given time interval. For more information, see Trigger an Event Policy Based on Event Count.

Correlating Events Based on Event Attributes

The attributes-match statement correlates two events as follows:

  • event1.attribute-name equals event2.attribute-name—Execute the policy only if the specified attribute of event1 equals the specified attribute of event2.

  • event.attribute-name matches regular-expression—Execute the policy only if the specified attribute of event matches the given regular expression. For more information, see Use Regular Expressions to Refine the Set of Events That Trigger a Policy.

  • event1.attribute-name starts-with event2.attribute-name—Execute the policy only if the specified attribute of event1 starts with the specified attribute of event2.

If the attributes-match statement includes the equals or starts-with option, or if it includes a matches option that includes a clause for an event that is not specified at the [edit event-options policy policy-name events] hierarchy level, then you must also define one or more within statements in the same event policy.

You can use event policy variables within the attributes-match statement to differentiate between a triggering event attribute and a correlating event attribute. Trigger events are those that you configure at the [edit event-options policy policy-name events] hierarchy level. The double dollar sign ($$) notation represents the event that is triggering a policy, and {$$.attribute-name} resolves to the value of the attribute of the triggering event. For correlating events, the single dollar sign with the event name ($event) notation represents the most recent event that matches the event name, and {$event.attribute-name} resolves to the value of the attribute associated with that event.

For example, the following event policy executes the actions under the then statement if four or more commits are performed within a 5-minute period and the username of one or more of the correlating events is the same as the username of the trigger event.

There are many ways to find the attributes that you can reference for a specific event, for example:

  • Use System Log Explorer.

  • Use the help syslog event operational mode command in the CLI.

  • Use context-sensitive help in configuration mode when you configure the attribute.

The System Log Explorer application enables you to search the standard system log messages for a given operating system and release. The message details include the attributes that you can reference for that event.

Alternatively, in the CLI, the help syslog event operational mode command also displays a list of the attributes that you can reference for a given event. The command output shows the event attributes in angle brackets (<>). The following output shows that the ACCT_ACCOUNTING_SMALL_FILE_SIZE event has three attributes that you can reference: filename, file-size, and record-size.

Note:

You can filter the output of a search by using the pipe (|) symbol. For more information about using the pipe symbol, see the CLI User Guide.

You also view event attributes by issuing the set attributes-match event? configuration mode command at the [edit event-options policy policy-name] hierarchy level, as shown in the following example:

Note:

In this set command, there is no space between the event name and the question mark (?).

How to Represent Triggering and Correlating Events in an Event Policy

In event script arguments and supported event policy statements such as the execute-commands statement, you can use event policy variables to differentiate between a triggering event and a correlating event. Triggering and correlating events are configured in the following statements at the [edit event-options policy policy-name] hierarchy level:

  • Triggering event—Configured in the events statement
  • Correlating event—Configured in the within seconds events statement

You can use event policy variables of the following forms to represent triggering and correlating events:

  • {$$.attribute-name}—The double dollar sign ($$) notation represents the event that triggers the policy. When combined with an attribute name, the variable resolves to the value of the attribute associated with the triggering event. For example, {$$.interface-name} resolves to the interface name associated with the triggering event.

  • {$event.attribute-name}—The single dollar sign with the event name ($event) notation represents the most recent event that matches event. When combined with an attribute name, the variable resolves to the value of the attribute associated with that event. For example, when a policy issues the show interfaces {$COSD_CHAS_SCHED_MAP_INVALID.interface-name} command, the {$COSD_CHAS_SCHED_MAP_INVALID.interface-name} variable resolves to the interface name associated with the most recent COSD_CHAS_SCHED_MAP_INVALID event cached by the event process.

  • {$*.attribute-name}—The dollar sign with the asterisk ($*) notation represents the most recent event that matches any of the correlating events. The variable resolves to the value of the attribute associated with most recent event that matches any of the correlated events specified in the policy configuration.

In event policies, you can reference specific events by using event policy variables. Consider the following event policy:

In the show interfaces {$$.interface-name} command, the value of the interface-name attribute of event e1, e2, or e3 is substituted for the {$$.interface-name} variable.

In the show interfaces {$e4.interface-name} command, the value of the interface-name attribute of the most recent e4 event is substituted for the {$e4.interface-name} variable.

In the show interfaces {$*.interface-name} command, the value of the interface-name attribute of the most recent e4, e5, or e6 event is substituted for the {$*.interface-name} variable. If one of e1, e2, or e3 occurs within 60 seconds after e4, e5, or e6, the value of the interface-name attribute for that correlating event (e4, e5, or e6) is substituted for the {$*.interface-name} variable. If the correlating event does not have an interface-name attribute, the software does not execute the show interfaces {$*.interface-name} command.

If e1 occurs within 60 seconds of both e4 and e5, then the value of the interface-name attribute for e4 is substituted for the {$*.interface-name} variable. This is because the event process (eventd) searches for correlating events in sequential order as configured in the within statement. In this case, the order is e4 > e5 > e6.

Example: Correlating Events Based on Receipt of Other Events Within a Specified Time Interval

The event policy in this example issues a set of commands and uploads the resulting output file to an archive site. The policy executes if one of the trigger events, event3, event4, or event5, occurs within 60 seconds after one of the correlating events, event1 or event2, occurs. The pseudocode for the policy is as follows:

The event policy specifies two archive sites in the configuration. The device attempts to transfer to the first archive site in the list, moving to the next site only if the transfer fails. The event policy configuration is:

Example: Correlating Events Based on Event Attributes

In the following event policy, the two events are correlated if their event attribute values match. Matching on the attributes of both events ensures that the two events are related. In this case, the interface addresses must match and the physical interface (ifd) names must match.

The RPD_KRT_IFDCHANGE error occurs when the routing protocol process (rpd) sends a request to the kernel to change the state of an interface and the request fails. The RPD_RDISC_NOMULTI error occurs when an interface is configured for router discovery but the interface does not support IP multicast operations as required.

In this example, rpd_rdisc_nomulti.interface-name might be so-0/0/0.0, and rpd_krt_ifdchange.ifd-index might be so-0/0/0.

Related Documentation