CustomPolicyEngined

Overview

The Unified Assurance Event Custom Action Policy Engine (CAPE) is a policy-based, multithreaded, multi-headed, and flexible correlation engine. It can be configured to run a variety of custom tasks on the Event stream before other actions are taken. CAPE allows for post-collection processing for enrichment and correlation outside of the database environment. Mix-and-match connectors (Generic Connector, Ticketing Connectors, Probable Root Cause Analysis) and agents (time of day correlation, time of day, existence or absence of events) and use any internal or external datasets to create custom correlation models. Utilize CAPE for northbound integration of Unified Assurance with an external ticketing system, enrichment/correlation of data, custom notifications as well as auto-remediation.

CAPE consists of two pieces:

• A CAPE Policy is used to select the data that will be processed by the node, as well as the other settings needed to process the returned data. Policies can be clustered across multiple running CAPE services or run from a specific CAPE service by setting the Zone ID on the policy and application configuration. For load balancing clustering use the Failover Type => Cluster on the CAPE service.

• A CAPE Node contains the Perl-based logic needed to process the data that was retrieved by the policy. CAPE Nodes can be chained to run after one another if additional processing is needed by setting the Next Node Condition and selecting the node that follows if condition is true. Nodes can also be aliased and called as functions from within another node's code for more complex decision trees.

Custom Action Policy Engine (CAPE) Setup

1. Add CAPE Nodes or modify existing CAPE Nodes which are run when a CAPE Policy detects an event that matches the criteria:

   Configuration -> Events -> CAPE -> Nodes

2. Add CAPE Policies or modify existing CAPE Policies that will poll the Events database for the specified events. Select the primary Custom Action Node created in the First Node Executed field.

   Configuration -> Events -> CAPE -> Policies

3. Enable the default Service, unless a specific configuration option is needed:

   Configuration -> Broker Control -> Services

Default Service

Default Configuration

Node Rules

CAPE Nodes are written in Perl syntax. For information about creating nodes, see the following in Unified Assurance Developer's Guide:

• Core for information about core rules functions.

• Events for information about Event rules functions.

• Application Logging

Tokens

CAPE exposes the following tokens for node processing.

$CustomHash->{SubObject} = &share({});

Example CAPE Setup

This example will demonstrate how threshold violation events can be checked to see if the device is reachable or not.

Dependencies

• System running the Ping Latency Poller and the Standard Thresholding Engine.

Steps

1. Log in to the Unified Assurance UI and go to the Nodes UI:

   Configuration -> Events -> CAPE -> Nodes

2. Click Add to bring up the form.

3. Give the Node a useful name and description.

4. Use the code below in the Node Text section:

   # This section grabs the values selected in the 'SELECT' statement used in the CAPE Policy configuration. Only things referenced in the SQL SELECT statement are available within the CAPE Node.
   my $EventID   = $EventData->{'EventID'};
   my $IPAddress = $EventData->{'IPAddress'};
   my $Severity  = $EventData->{'Severity'};
   
   # Due to the SQL code used, every event that gets pulled back are DeviceUpDown events, which get created due to the Threshold Engine for the Device Down threshold. The CAPE Policy created will now attempt to ping the device and store the result of the attempt into the $ping variable.
   $Log->Message("DEBUG", "Running Ping check command");
   my $ping = `ping -c10 $IPAddress`;
   $Log->Message("DEBUG", "Result of Ping test ----> [ $ping ]");
   
   # If the result of the ping contains the text 'ttl', the ping was successful, so the event severity will be set to '0' (cleared) and a log message is saved to the CAPE log.  If the ping failed, the event severity will be set to '5' (critical).
   if ($ping =~ m/ttl/i){
      $Log->Message("DEBUG", "Result of Ping Test successful, suppressing event");
      $Severity = 0;
   }
   else {
      $Log->Message("DEBUG", "Result of Ping Test failed, escalating event");
      $Severity = 5;
   }
   
   # An Alarm Journal entry is created for the EventID in question with the output of the ping from the previous step.
   $Log->Message("DEBUG", "Inserting into Journal [$EventID:$ping]");
   my ($ErrorFlag, $Message) = AddJournal({
       DBH       => \$EventDBH,
       EventID   => $EventID,
       TimeStamp => time(),
       Username  => '1',
       Entry     => $ping,
       ShardID   => $AppConfig->{'ShardID'}
   });
   
   # The next step is to update the Alarm with new information. The severity is updated (if ping was successful), and also update Custom5 so that this event is not caught be the CAPE Policy SQL code again.  This prevents CAPE re-processing events it has previously acted upon.
   $Log->Message("DEBUG", "Updating alarm entry [$EventID:$Severity]");
   my ($ErrorFlag, $Message) = UpdateEvent({
       DBH     => \$EventDBH,
       EventID => $EventID,
       ShardID => $AppConfig->{'ShardID'},
       Values  => {
           Severity => $Severity
       }
   });
   

5. Via the UI, go to the Policies UI:

   Configuration -> Events -> CAPE -> Policies

6. Click Add to bring up the form.

7. Give the Policy a useful name and description.

8. Set the Poll Interval to 5 minutes; this will cause the SQL to be run every 5 minutes against the event list.

9. Select the First Node Executed to be the corresponding Node created in the previous steps.

10. Use the query below Event Select Statement:

    SELECT EventID, Severity, IPAddress
      FROM Events 
     WHERE Severity   = 5 
       AND AlarmGroup = "DeviceUpDown"
    

11. Enable the default Service, unless a specific configuration option is needed:

    Configuration -> Broker Control -> Services

Administration Details

The following list shows the technical details you will need for advanced administration of the application:

• Package - coreProcessing-app

• Synopsis - ./CustomPolicyEngined [OPTIONS]

• Options:

   -c, --AppConfigID N   AppConfigID => Application Config ID (Service, Job, or Request ID)
   -?, -h, --Help        Print usage and exit
  

• Threaded - Multithreaded