Manage Correlation Rules

Correlation instances are required to run correlation rules. A correlation instance includes an ECL ruleset, which is effective as soon as the correlation instance is active.

There are two types of instances, replay and real-time.

Replay Instances

Replay instances work on historical data. When you run an Advanced Search with a correlation Blok from the GUI, a corresponding replay instance is automatically created and executed.

You can perform the following operations on replay instances using REST API:

  • Create a replay instance using ECL: 
    POST http://<host>:9682/api/v1/instances
    Ensure that you specify "instanceType": "replay". Note down the instance ID returned in the response body.
  • Check the status of the instance to ensure it has finished processing the historical data: 
    GET https://<host>:9682/api/v1/instance/<instanceID>
    "status": "completed" indicates that the instance has processed all the historical data in the system.
  • Retrieve the correlation events to ensure the rule is operating as expected. 
    GET https://<host>:9682/api/v1/instance/<instanceID>/correlationevents?type=MESSAGES
  • If the output is not as expected, update the instance with new ECL and view the new results. 
    POST https://<host>:9682/api/v1/instance/<instanceID>
    After updating the instance, the modified rule is applied to the data and a new set of correlation events is generated.
  • Delete the instance to free all the resources being used by the instance: 
    DELETE https://<host>:9682/api/v1/instance/<instanceID>

Real-Time Instances

Real-time instances work on real time events. When you create triggers and trigger groups from the GUI and synchronize trigger groups, a real-time instance is automatically created for each trigger group. The real-time instance includes all information associated with that trigger, such as correlation Blok and notification settings.

Real-time instances process only the new data ingested in the appliance. Therefore, after creating a real-time instance, you must wait until new data arrives before any alerts can be generated.

To create a real-time instance using REST API, use the same resource URL as that for creating replay instances; but specify "instanceType": "realtime". REST API services for other operations are the same as those for replay instances.

Real-time instances generate alerts. To retrieve and acknowledge alerts using the REST API, see Retrieve and Acknowledge Alerts.

List of REST API services

Resource API Description
GET activeInstances Get a list of active instance states that currently exist in the node.
GET instances Get a list of instances that currently exist in the node.
POST instances Create a new instance and run it on the specified data.
GET instance/{id} Get the summary of an instance.
POST instance/{id} Update the state of an instance.
DELETE instance/{id} Delete an instance from the node.
GET instance/{id}/correlationevents Get correlation events for an instance. This supports only replay instances.
GET instance/{id}/correlationevent/{eventId}/group/{name}/eventKeys Get a list of event references and sources. This supports only replay instances.
GET instance/{id}/result/{resultSetId}/columns Get lists of correlation result set columns. This supports only for replay instances.
PUT validate/correlation/rule Validate a correlation rule.

Limitations

You can use correlation instances from the REST API, but not from the GUI, because of the following reasons:

  • A correlation instance created by using the REST API service cannot be viewed or edited from the GUI.
  • A real-time correlation instance updated by using the REST API service is not synchronized with its corresponding triggers and trigger group created from the GUI. Similarly, a replay instance updated by using the REST API service is not synchronized with its corresponding search query created from the GUI.