Skip to content

Assure1 Event Generic Agent

Overview

The Assure1 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 Assure1.

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

  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 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.

  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 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

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

  3. Add the Configuration option SourceSchemaName with the value "Historical" (without the quotes).

  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

  • 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 Assure1 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 needed 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