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 eventanalytics is still present in the current Events database.
Generic Agent Setup
-
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.
-
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 executed 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 executed for each event that is selected from the query above.
-
PostRules will be executed after all events have been processed.
Update the logic as needed.
-
-
Enable the default Job, unless a specific configuration option is needed.
Using the Historical Database
-
Make sure that the query in the SelectSQLFile file is appropriate for reading from the eventanalytics 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
-
Optional Clone the default Job, and change the configuration of the clone.
-
Add the Configuration option SourceSchemaName with the value "Historical" (without the quotes).
-
Run the Job on an appropriate schedule. !!! note "Every minute" is unlikely to be an appropriate schedule for querying the Historical database.
-
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
-
The default job configuration is to run every minute.
-
Make sure that events that were selected for processing are updated so they would be not be processed again during the next execution cycle.
Rules
This agent uses the Unified Assurance standard rules architecture, which are 100% Perl syntax. Refer to the following articles to assist in node rules creation:
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:
-
Package - coreCollection-app
-
Synopsis -
./GenericAgent [OPTIONS]
-
Options:
-c, --AppConfigID N Application Config ID (Service, Job, or Request ID) -?, -h, --Help Print usage and exit
-
Threaded - Multi-Threaded