Event processing in agents
To process events, agents must subscribe to the event types that they want to receive. Incoming events are routed to agents based on the information from the agent descriptor file and on the entity ID that is available inside the event.
An agent can subscribe to several event types, but processes only one event at a time. If several agents process the same event against the same entity, you can set priorities to define which agent must process the event first. All agents that process an event against a single entity instance are processed in sequential order according to priority. If any of the agents emit an event that also processes the same entity, these events are processed after the first set of agents complete.
When an agent processes an event, it can complete successfully or not; there is no partial completion. When event processing fails, it is attempted again, if it is recoverable. If there are too many attempts, or if the error is unrecoverable, processing of that event against the entity is logged and abandoned.
If an event type is subscribed to by agents, and these events are associated with different entities then they are processed in parallel. The order in which events are processed when multiple entities are involved is unpredictable. Agents must not rely on a processing order when a single event is associated with more than one entity.
In general, when multiple events are associated with the same bound entity, the order in which they are processed is the order in which they are received. However, the order is not assured, because failure or something else might prevent the system from keeping the exact order. When events are received at the same time, the system selects the first emitted event by using the source of the event.
Event processing differences depend on the type of agent that receives the event. Rule agents process events differently to Java™ agents.
Event processing in rule agents
When an event arrives in a rule agent, the event is inserted into the local working memory of the agent to store the time of the event and the information that is contained inside the event. Agents process events in the order that they come into Insight Server. The order does not depend on the emission time of the event but on the arrival time in the agent. Rule agents process incoming events by using condition-action rules.
Rules are written in a rule language and are used to detect situations of interest in time and geographic location. Rules are used to match stateful knowledge and situational context, and to make insightful decisions from this data. The rules process the incoming events immediately or after the reception of the events by using different constructs in the rule language. A rule can refer to the current event, the bound entity, create and update a bound entity, detect multiple instances of an event type, test the history of preceding events, get values of aggregates, and emit a new event.
The following diagram shows the rule syntax to process the incoming event and to take an appropriate action based on the situation. The diagram is an image map, which provides hover links to more detailed information about the following topics.
So that rules can operate over time and events can be placed into order, Insight Server uses a reference parameter named now. now is a time parameter that represents the most recent event time stamp that is received in the agent. now is also advanced when an agent does time-based processing. now always increases in time when new events arrive. Setting now to the most recent event time stamp prevents the runtime clock from moving backwards in time. In rules, now is implicit unless you want to take a specific action that is based on another time, like the time stamp of an event.
If a rule agent receives a stream of events or time triggers it processes one after the other in the order it receives them. The processing of an event or a time trigger includes the following steps:
- The state is updated, that is, the values of now and currentEvent are updated. If an event is processed, it is added to the working memory.
- The rule engine is invoked and rules are executed until all applicable rules are acted upon. The rule engine must finish the processing of the current event before it begins the processing of the next.
A rule can either process an event immediately or postpone the processing:
- Rules that process an event immediately
- The rule reacts to an incoming event as soon as the agent receives
this event.
In a rule, the immediate processing of the event is expressed by a when <event> occurs clause. The event that occurs is the event that the agent received. The rule that acts upon arrival of this event is only valid at the time when the agent receives the event. This rule is only applicable at the reception of the event and it is not applicable to events that were previously processed by the agent.
In the following example, Event A is the most recent event that is received, and now is the time stamp of Event A.
In some cases, an event might arrive out-of-order and now has the value of another time stamp, see Order of events.
- Rules that postpone the processing of events
- This type of rule processes an event at a specified time point after the reception of the event,
and reacts after a specified duration. The rule is applicable only when this condition is met. A
time triggered event is sent when the postponed duration is expired.
In a rule, the postponed processing of an event is expressed by the clause when <event> has occurred <calendar duration> ago. The postponed processing is based on the time stamp of the incoming event and a fixed calendar duration.
The following figure shows that Event A is the reference event. Event A already occurred and the time stamp of the Event A is before the time now.
- Order of events
An external event has a time stamp that is defined in the time scale of the application. External events are often received by an agent with a delay compared to their time stamp. The delay might vary depending on the events and on the agents. Some events might have a greater delay than others and might be received later by the agent. Therefore, external events might not be received in increasing order of their time stamps. An event is out-of-order if it is received after an event with a later time stamp.
The following example shows three delayed events that arrive one after the other. Delayed events, which are not out of order, are of no consequence to the agent. The agent processes them at the correct logical time.
- Event A has a time stamp at 10:12:10, and it arrives first in the rule agent with a 2-seconds delay. The time component now is updated with the time stamp of Event A.
- Event B arrives after Event A, and now is updated with the time stamp of Event B.
- Event C arrives after Event B, and now is updated with the time stamp of Event C.
The following example shows three delayed events that arrive not in the same order as the time stamps. Event A has a time stamp at 10:12:10 but it arrives 10 seconds later in the rule agent. Therefore, Event A arrives after Event B, which arrives at 10:12:17. Event A is out-of-order.
- Event B arrives in the rule agent, and now is updated with the time stamp of Event B.
- Event A arrives in the rule agent, and now keeps the time stamp of Event B.
- Event C arrives in the rule agent, and now is updated with the time stamp of Event C.
You can write rules to detect the absence of an event or check that an event is the most recent event that is received in the agent.
Event processing in Java agents
Java agents subscribe to events in the agent descriptor file, in the same way as rule agents. However, the processing of events is different in Java agents and rule agents.
When an event arrives in the Java agent, the process method is called, and the logic that is described in the agent is executed. Java agents have no concept of now, and therefore do not detect out of order events. However, Java agents are free to use the time stamp of the event in processing.