Configuring Alert Latency with Event Generation Framework

Overview of Event Generation Framework

When a SAS BI Dashboard user or modeler sets up an alert, Event Generation Framework regularly polls BI Dashboard indicators, determines whether an event qualifies for an alert, and generates an alert for the user. An alert notification is generated when an indicator meets the criteria configured for the alert. Alerts are generated via e-mail, or they are posted as an event to the Alerts portlet.

Some organizations might receive an alert once a quarter or once a month. Organizations that require operational data can receive alerts as frequently as once a minute or more often.

The SAS BI Dashboard User's Guide explains about how to configure SAS BI Dashboard indicators, ranges, and threshold for alerts. It also provides information about how to select the frequency and mode of output for alert notifications.

The following figure shows how the Event Generation Framework interacts with the SAS BI Dashboard indicators to poll for an event, trigger the event, and notify users through an alert notification service.

Event Generation Framework

Customizing Time Intervals for Alert Latency

Constant polling can impact the efficiency of SAS BI Dashboard. In order to minimize the impact of constant polling on performance of SAS BI Dashboard, you can customize and set parameters for alert latency. Alert latency is the time lag between when a data change occurs that triggers an alert and the time a user receives that alert.

To ensure optimum efficiency with alert latency, you can customize the time intervals for configuration data files in metadata. These configuration data files include EventSourceCandidateRefHandler and the EventCandidateRequestHandler. The EventSourceCandidateRefHandler is responsible for polling SAS BI Dashboard for a list of indicators that need to be queried. The EventCandidateRequestHandler retrieves a group of indicators in the list each time, and analyzes each indicator to determine whether an event should be generated.

The following table shows the location of the files and the parameters that can be customized in each of these files.

Parameters for Event Generation

Parameter	Path	File
heartbeatinterval	SAS Folders/System/Applications/SAS BI Dashboard/BI Dashboard 4.3/BI Dashboard 4.3 - Event Generator/CandidateRefHandlerConfigs	`biDashboardIndicatorHeartbeat.crh`
throttlepause	SAS Folders/System/Applications/SAS BI Dashboard/BI Dashboard 4.3/BI Dashboard 4.3 - Event Generator/CandidateRequestHandlerConfigs	`BIDashboardIndicatorRequestor.crh`

Default Values for Alert Latency

Overview

Alert latency is accomplished by two parameters:

heartbeatinterval
throttlepause

Default Value for heartbeatInterval Parameter

The heartbeatinterval parameter determines how often the EventSourceCandidateRefHandler polls for the list. In SAS BI Dashboard 4.3, the heartbeatinterval parameter determines how often the getCandidateIndicatorList is called upon. The default value for the heartbeatinterval parameter is 180000 milliseconds or 3 minutes.

Here is an example of the default value for the heartbeatinterval parameter in the biDashboardIndicatorHeartbeat.crh file for SAS BI Dashboard 4.3:

<?xml version="1.0" encoding="UTF-8"?>
EventCandidateRefHandlerConfig classname="com.sas.bi.dashboard.egfhandlers.
BidEventCandidateRefHandler"
     endpointSoftwareComponentName="BI Dashboard 4.3"
     heartbeatInterval="180000"
     id="biDashboardIndicatorHeartbeat"
serviceEndpointUrl="/services/AlertService/getCandidateIndicatorList"

Default Value for throttlepause Parameter

The EventCandidateRequestHandler is responsible for requesting a small number of indicators at a time. The throttlepause parameter determines how often the EventCandidateRequestHandler requests the small number of indicators. After a request is completed, the system pauses for the number of milliseconds specified by the throttlepause parameter before issuing the next request. The EventSourceCandidateRefHandler puts less strain on the SAS BI Dashboard. Therefore, this call can be made more frequently with less performance impact. The throttlepause parameter is set to a default value of 60000 milliseconds.

Here is an example of the default value for the throttlepause parameter in the BIDashboardIndicatorRequestor.crh file for SAS BI Dashboard 4.3:

<?xml version="1.0" encoding="UTF-8"?>
<EventCandidateRequestHandlerConfig
classname="com.sas.bi.dashboard.egfhandlers.
IndicatorRequestHandler"
     defaultEventCandidateType="sas.bid.indicator"
     endpointSoftwareComponentName="BI Dashboard 4.3"
      id="BIDashboardIndicatorRequestor"
      requestorType="sas.bid.indicator"
      serviceEndpointUrl="/services/AlertService/getAlertIndicators"
      throttlePause="60000">

Guidelines for Modifying the Default Interval Values for heartbeatInterval and throttlepause Parameters

The values specified for the heartbeatInterval and the throttlePause parameters determine how often the Event Generation Framework polls BI Dashboard indicators, and how quickly alerts are processed. Depending on your business requirements, you can modify the interval values for these parameters. Some businesses might choose to have an aggressive value of 30 seconds or specify a value equal to a few minutes. Other businesses might choose a higher value equal to several hours (for example, three hours or six hours). The values are always specified in milliseconds.

If you want to modify the interval values for heartbeatintervaland throttlepause parameters, consider these factors:

Does the data in your organization change often?
Do the users need to be notified immediately if the Alert threshold is met?

If your dashboard users have indicators that contain stable data (for example, the data changes once a day, once a week, or once a month), then running the Event Generation Framework once every three minutes might not be optimal. In this case, you can reduce the system overhead by increasing the intervals for the heartbeat and the throttlePause parameters.

Dashboard users can control the frequency of alert notifications by selecting the option Limit alerts on frequently changing indicators. This option in the Alerts screen within SAS BI Dashboard applies to an individual alert. It is designed to prevent users from being flooded with e-mails or Alert Portlet notifications for indicators with frequent data changes. The shortest notification interval that can be set by the user within an alert is one hour.

A dashboard user might limit an e-mail or Alerts Portlet notification to once a day. Even if the Event Generation Framework executes once every 3 minutes and detects a change in data, the e-mail or the Alert Portlet notification is generated only once a day for that user.

Logging Output for Event Generation

Beginning with SAS 9.3, the SAS Web Infrastructure Platform has implemented a framework for providing separate logging contexts for the individual SAS Web applications. Web application servers have a property defined on their command line (com.sas.log.config.url) that points to the directory where the log4j configuration files are located.

For event generation, the SASBIDashboardEventGen-log4j file is located in the SAS-Configuration-Directory\Levn\Web\Common\LogConfig directory.

Message logging is accomplished by adding an appender section in the SASBIDashboardEventGen-log4j file. A logging context is the fully qualified class name of the class where the logging message originated. The com.sas.bi.eventgen logging context is specific to event generation. The com.sas.bi.eventgen logging context applies to event generation.

By default, all event generation log messages go to both the application server console and the event generation log file. The SASBIDashboardEventGen4.3 log file is stored in the SAS-configuration-directory \Lev1\Web\LogConfig directory.

For more information about logging as it applies to all Web applications, see the SAS Intelligence Platform: Middle-Tier Administration Guide.