On Message State Change
AMPS provides two modules, amps-action-on-alert
and amps-action-on-message-condition-timeout
, to run an action when a message in a SOW topic meets a specific condition for longer than a specified period of time. These modules provide a way to track specific messages in a SOW topic and indicate whether the message has timed out (that is, been in the monitored state longer than expected) or whether the message has been processed as expected and is no longer being tracked within the specified timeout.
The amps-action-on-alert
action monitors a SOW topic for messages that match a filter and triggers an action when either:
The message has remained matched on the filter for at least the specified duration (indicating a timeout), or
An out-of-focus message is received for the message (indicating that the message is no longer tracked)
The amps-action-on-message-condition-timeout
action monitors a SOW topic for messages that match a filter and triggers an action when:
The message has remained matched on the filter for at least the specified duration (indicating a timeout)
Use amps-action-on-message-condition-timeout
if only timeouts are important, otherwise use amps-action-on-alert
if both timeouts and message tracking are important.
For example, a set of actions might be configured to publish a message to an Alerts
topic if an order is unprocessed for more than a specified timeout. When the order is processed, the actions might publish a message to a Statistics
topic for tracking purposes. Rather than creating two independent actions, which could lead to overlap if the order is processed at the same time that the alert is being generated, use this action to guarantee that only one of the events will be generated.
The module tracks each message that matches the filter individually, and will run once for each message tracked.
This module uses the Out-of-Focus notification (OOF) mechanism. When a message matches the specified topic and filter, the module begins tracking that message. If no OOF notification is received for that message within the specified timeout, the action runs for that message and indicates that the timeout has been exceeded. If an OOF notification is received before the timeout expires, then the action runs for that message, indicating that the message is no longer tracked.
This module uses the custom event system as a way of indicating whether a given message was removed from tracking, or whether the message timed out. When configuring the action, you specify the event to raise for each of these states. This module stores the exact event raised in a context variable, which you can then use with amps-action-do-event
to raise the event.
While the AMPS server is running, this action will trigger exactly once for each message after it reaches the timeout period. When AMPS restarts, if a message that had previously triggered this action still exists in the SOW topic (and still matches the filter provided, if any), the action will run for that message immediately after the module initializes on restart.
This action requires the following parameters. In addition to that, this module also accepts the optional parameters listed below:
Topic
(required)
The name of the topic to monitor for messages.
This parameter does not support regular expressions. The topic name must be either a SOW topic, a view or a conflated topic.
Queues are not supported.
There is no default for this parameter.
MessageType
(required)
The message type of the topic to monitor for messages.
There is no default for this parameter.
OOFEvent
(required)
The value to store when an out-of-focus notification is received for a tracked message.
There is no default for this parameter.
TimeoutEvent
(required)
The value to store when a message is in the tracked state for longer than the timeout period.
There is no default for this parameter.
EventVariable
(required)
The name of the context variable in which to store the reason that the action is running (either the string in OOFEvent
or the string in TimeoutEvent
).
There is no default for this parameter.
Duration
The amount of time to wait for an OOF notification for the message before running the action.
Filter
Sets the filter to apply.
Only messages that match this filter will be monitored by this action. If no filter is provided, every message of the specified message type in topics that match the Topic
value will be monitored.
The module adds the following variables to the AMPS context:
AMPS_TOPIC
The topic of the message that triggered the alert.
AMPS_DATA
The current data of the message.
AMPS_DATA_LENGTH
The length of the current data of the message, in bytes.
AMPS_BOOKMARK
The bookmark of the message. Empty if there is no bookmark for the message.
AMPS_TIMESTAMP
The timestamp at which the module began tracking the message.
AMPS_CLIENT_NAME
The client name of the current value of the message.
AMPS_SOW_KEY
The current SowKey for the message.
The variable specified in EventVariable
The reason the action is running. This will be either the value of OOFEvent
or the value of TimeoutEvent
, depending on what caused the action to run.
Last updated