GenericAgent

Overview

The Unified Assurance Event Generic Agent is a generic events processing engine that allows you to create custom event enrichment actions via rules. The agent polls the Events database using a custom SQL statement, parsing the results with the customized rules and creating or modifying events within Unified Assurance.

It can alternatively poll the historical database, processing the results with customized rules; it does allow events to be modified, but there is no general guarantee that the EventID from historical event analytics is still present in the current Events database.

Generic Agent Setup

  1. Review the query in the SelectSQLFile file referenced in the configuration to see the events that will be selected for processing. Update the query as needed.

  2. Review the logic in the rules files referenced in the configuration to see the processing that will be done on the events that are selected:

    • LoadRules will be run during application startup to load data that might be needed during processing.

    • IncludeRules will be read during application startup to load additional files that might be called during processing.

    • BaseRules will be run for each event that is selected from the query.

    • PostRules will be run after all events have been processed.

    Update the logic as needed.

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

    Configuration -> Broker Control -> Jobs

Using the Historical Database

  1. Make sure that the query in the SelectSQLFile file is appropriate for reading from the event analytics indices; it uses the elasticsearch sql feature, which is documented (along with its limitations) at https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-sql.html

    The query will likely be of the form

    SELECT /fields/ FROM "eventanalytics*" WHERE /conditions AND/ LastReported > TODAY() - INTERVAL 3 DAYS

  2. Optional Clone the default Job, and change the configuration of the clone.

  3. Add the Configuration option SourceSchemaName with the value Historical.

  4. Run the Job on an appropriate schedule.

    Note:

    Every minute is unlikely to be an appropriate schedule for querying the Historical database.

  5. Tuning: The fetch_size for the elasticsearch query can be set using the Configuration option MaxBatchSize, if the default is inadequate.

Default Scheduled Job

Field Value
Package Name coreCollection-app
Job Name Event Generic Agent
Job Program bin/core/collection/GenericAgent
Job Arguments
Job Description Event Polling for Event Correlation
Failover Type Standalone (Supported: Standalone, Primary/Backup)
Status Disabled
Privileged (Checked)
Minutes *
Hours *
Days *
Months *
WeekDays *

Default Configuration

Name Value Possible Values Notes
BaseRules collection/event/agent/base.rules Text, 255 characters Relative path to Base Rules.
BranchDir core/default Text, 255 characters relative path to Rules dir.
IncludeRules collection/event/agent/base.includes Text, 255 characters Relative path to Include Rules.
LoadRules collection/event/agent/base.load Text, 255 characters Relative path to Load Rules.
LogFile logs/EventGenericAgent.log Text, 255 characters Relative path to Log File.
LogLevel ERROR OFF, FATAL, ERROR, WARN, INFO, DEBUG Logging level used by application.
PostRules collection/event/agent/base.post Text, 255 characters Relative path to Post Rules.
SelectSQLFile collection/event/agent/events.sql Text, 255 characters Relative path to SQL file containing database query.
ShardID 1 Integer Database shard to be used.

Best Practices

Rules

This agent uses the Unified Assurance standard rules architecture in Perl syntax. For information about creating rules, see the following in Unified Assurance Developer's Guide:

Tokens

The agent exposes the following tokens for rules processing.

Token Description
$AppConfig Hash reference to the application configuration name-value pairs that were configured. (i.e. use $AppConfig->{'Host'} to retrieve the set value for 'Host'.)
$EventRow Resulting data from query. Use $EventRow->{'FieldName'} to access the FieldName data.

Administration Details

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