Setting a maximum time horizon for events

You can control how long events remain visible to the solution by configuring the time horizon in the agent descriptor when you create an agent, or by using the maxHorizon property in the solution_properties.xml file.

About this task

The time horizon specifies how long events remain visible to the solution. The maxHorizon property limits the horizons that are used by the solution to control the database and memory requirements for storing events. To learn more about setting the time horizon at the agent level, see Completing the agent descriptor.

If a solution accepts many events, from IOT sensors for example, then it is imperative that agents do not store all of the events in the database. To improve performance and prevent the storage of event types that occur in high volumes, set the duration of the event horizon to 0 in all of the agent descriptors that process them.

A horizon is always used. When a time horizon is not defined for an event in the agent descriptor, the maxHorizon solution property is used. If no time horizon exists in the agent descriptor and no maxHorizon solution property is defined, the system uses the default of 30 days. The longest time that you can set for maxHorizon is 68 years. For more information, see Solution properties.

Events that are older than the time horizon are no longer visible to the solution. Events past the horizon are not considered in the calculation of aggregates or event correlation. The maxHorizon property defines a maximum time horizon that determines how long events are retained.

The maxHorizon property overrides the time frame that is defined in a rule. For example, if a rule includes the following statement: 
the number of purchase events in the last period of 1 year
And the maxHorizon is set to P6M (6 months), then the rule operates on events that are created in the past 6 months instead of 1 year.

In a production server with data persistence enabled, events that exceed the specified time horizon remain in the backup database even when they are removed from the grid. Events are removed from the grid before the specified time horizon only when the eventCacheDuration property value is smaller than the maxHorizon. Each server monitors the number of events per event type per server that are removed from the grid.

Events are removed from the database periodically after they exceed the maxHorizon.

Procedure

  1. Open the solution_properties.xml file that is in the root folder of the solution project.
  2. Add the maxHorizon property for the solution or agent to the file.

Example

The following maxHorizon property applies to the entire solution and is set to 6 months.
<property name="maxHorizon">P6M</property>

The following example sets the horizon of an event type highVolumeEvent to 0 in an agent descriptor that processes this event type:

'AgentA' is an agent related to a PersonOfInterest , 
processing events : 
   - highVolumeEvent , 
      where this PersonOfInterest comes from the PersonOfInterest of this highVolumeEvent , 
      with a horizon of 0 seconds

Setting the horizon to 0 removes all of these events from the grid after they are processed and does not store them in the database. In the following cases, the events are stored in the database even if the horizon is set to 0 seconds:

  • events that are used to initialize an entity
  • events that are used in a shared aggregate