24. Automating AMPS With Actions¶
AMPS provides the ability to run scheduled tasks or respond to events, such as Linux signals, using the Actions interface.
To create an action, you add an Actions
section to the AMPS
configuration file. Each Action
contains one (or more) On
statement which specifies when the action occurs, and one (or more)
Do
statement which specifies what the AMPS server does for the
action. Within an action, AMPS performs each Do
statement in the
order in which they appear in the file.
AMPS actions may require the use of parameters. AMPS allows you to use variables in the parameters of an action. You can access these variables using the following syntax:
{{VARIABLE_NAME}}
AMPS defines a set of default variables when running an action. The event, or a previous action, can add variables in the context of the action. Those variables can be expanded in subsequent parameters. If a variable is used that isn’t defined at the point where it is used, AMPS will expand that variable to an empty string literal. The context can also be updated as the module is running, so any variables that are available at any given point in the file depend on what action was previously executed.
By default, AMPS loads the following variables when it initializes an AMPS action:
Variable | Description |
---|---|
AMPS_INSTANCE_NAME |
The name of the AMPS instance. |
AMPS_BYTE_XX |
Insert byte XX, where XX is a 2-digit uppercase hex number (00-FF). AMPS expands this variable to the corresponding byte value. These variables are useful for creating field separators or producing characters that are not permitted within XML |
AMPS_DATETIME |
The current date and time in ISO-8601 format. |
AMPS_UNIX_TIMESTAMP |
The current date and time as a UNIX timestamp. |
Table 24.1: Default Context Variables
An example to echo a message when AMPS starts up is shown below. Note the AMPS_INSTANCE_NAME is one of the variables that AMPS pushes to the context when an action is loaded.
<Actions>
<Action>
<On>
<Module>amps-action-on-startup</Module>
</On>
<Do>
<Module>amps-action-do-echo-message</Module>
<Options>
<Message>instance={{AMPS_INSTANCE_NAME}}</Message>
</Options>
</Do>
</Action>
</Actions>
AMPS actions are implemented as AMPS modules. To run each statement, AMPS
simply calls the module that implements that Do
statement. The module is
free to take any necessary actions. If a Do
statement returns
a failure, AMPS does not run subsequent Do
statements in that action.
This is intended to help make maintenance processes reliable. For example,
if a Do
statement that is intended to copy a log file to a storage
directory fails because the device that holds the storage directory is
not mounted, further steps in the action – which might do things like
remove the log file from the original directory – should not be run. Likewise,
if AMPS exits unexpectedly during a given Do
statement, subsequent
statements will not be run.
AMPS provides the modules described in the following sections by default.
Configuration for Actions¶
This section lists configuration parameters for actions.
On Element: When an Action Runs¶
This section describes the options for configuring when AMPS runs a given action.
Running an Action on a Schedule¶
AMPS provides the amps-action-on-schedule
module for running actions
on a specified schedule.
The options provided to the module define the schedule on which AMPS will run the actions in the Do element.
Parameter | Description |
---|---|
Every
|
Specifies a recurring action that runs whenever the time matches the provided specification. Specifications can take three forms:
AMPS accepts both local time and UTC for time
specifications. To use UTC, append a |
Name |
The name of the schedule. This name appears in log messages related to this schedule. Default: |
Table 24.2: Parameters for Scheduling Actions
This module does not add any variables to the AMPS context.
Running an Action in Response to a Signal¶
AMPS provides the amps-action-on-signal
module for running actions
when AMPS receives a specified signal.
The module requires the Signal
parameter:
Parameter | Description |
---|---|
Signal
|
Specifies the signal to respond to. This module supports the standard Linux signals. Configuring an action uses the standard name of the signal. For example, to configure an action to AMPS reserves |
Table 24.3: Parameters for Responding to Signals
This module does not add any variables to the AMPS context.
Actions can be used to override the default signal behavior for AMPS. |
Default Signal Actions¶
By default, AMPS registers the following actions for signals.
On Event | Action |
---|---|
SIGUSR1 |
amps-action-do-disable-authentication |
SIGUSR1 |
amps-action-do-disable-entitlement |
SIGUSR2 |
amps-action-do-enable-authentication |
SIGUSR2 |
amps-action-do-enable-entitlement |
SIGINT |
amps-action-do-shutdown |
SIGTERM |
amps-action-do-shutdown |
SIGHUP |
amps-action-do-shutdown |
Table 24.4: Default Actions
The actions in the table above can be be overridden by creating an explicit action in the configuration file.
AMPS reserves the SIGQUIT
signal, and does not allow the
configuration file to override the action taken in response
to SIGQUIT
:
On Event | Action |
---|---|
SIGQUIT |
amps-action-do-minidump |
Table 24.5: Reserved signal
Running an Action on Startup or Shutdown¶
AMPS includes modules to run actions when AMPS starts up or shuts down.
The amps-action-on-startup
module runs actions as the last step in
the startup sequence. The amps-action-on-shutdown
module runs
actions as the first step in the AMPS shutdown sequence.
In both cases, actions run in the order that the actions appear in the configuration file.
These modules do not require any parameters.
These modules do not add any variables to the AMPS context.
Running an Action on Client Logon¶
AMPS provides the amps-action-on-logon-client
module for running actions
when a user logs into an AMPS client.
This module does not require any parameters.
This module adds the following variables to the AMPS context:
Variable | Description |
---|---|
AMPS_CLIENT_NAME |
The name of the AMPS client. |
AMPS_CONNECTION_NAME |
The name of the AMPS connection. |
AMPS_AUTHENTICATION_ID |
The authentication id of the AMPS connection. |
Table 24.6: Context Variables for On Client Logon
Running an Action on Client Connection¶
AMPS provides modules for running actions on the connection or disconnection of an AMPS client.
The amps-action-on-disconnect-client
runs actions once an AMPS
client instance disconnects. The amps-action-on-connect-client
runs
actions once an instance of an AMPS client successfully connects.
These modules do not require any parameters.
These modules add the following variables to the AMPS context.
Variable | Description |
---|---|
AMPS_CLIENT_NAME |
The name of the AMPS client. |
AMPS_CONNECTION_NAME |
The name of the AMPS connection. |
AMPS_AUTHENTICATION_ID |
The authentication id of the AMPS connection.
(for on-disconnect-client action only) |
Table 24.7: Context Variables for On Connect and Disconnect Client
Running an Action on Message Delivery¶
AMPS provides modules to run actions when AMPS delivers a message to subscribers. The basic flow of AMPS messaging is to first receive a published message, find the subscriber(s) to which this message will be sent, then deliver the message.
The amps-action-on-deliver-message
runs actions when AMPS delivers a
publish
message to subscribers.
This module requires the MessageType
and the Topic
of the
message that has been delivered:
Parameter | Description |
---|---|
MessageType
|
The message type of the topic to monitor for message delivery. There is no default for this parameter. |
Topic
|
The name of the topic to monitor for message delivery. This parameter supports regular expressions. There is no default for this parameter. |
Table 24.8: Parameters for On Deliver Message
This module adds the following variables to the AMPS context:
Variable | Description |
---|---|
AMPS_TOPIC |
The topic of the message. |
AMPS_DATA |
The data the message contains. |
AMPS_DATA_LENGTH |
The length of the data the message contains. |
AMPS_BOOKMARK |
The bookmark associated with this message. This is an empty string if the message does not have a bookmark. |
AMPS_CLIENT_NAME |
The name of the client to which this message was delivered. |
AMPS_CORRELATION_ID |
The correlation id set on the publish command, if one was set. |
Table 24.9: Context Variables for On Deliver Message
Running an Action on Message Publish¶
AMPS provides modules to run actions when a message is published to AMPS. The basic flow of AMPS messaging is to first receive a published message, find the subscriber(s) to which this message will be sent, then deliver that message to the subscriber(s).
The amps-action-on-publish-message
runs actions as soon as a message
is published to AMPS.
This action is treated by the AMPS engine as a subscription from an internal AMPS client. When working with queues, use this action with the underlying topic of the queue rather than the queue topic itself. Because this action creates a subscription, using this action with the queue topic will cause the action to lease messages from the queue even though the action does not acknowledge messages. This means that, when used with the queue topic itself, the action will interfere with other subscribers and, depending on the queue configuration, may only receive one message during the lifetime of the instance. |
This module requires the MessageType
and the Topic
of the
message that was published. In addition to that, this module also
accepts optional parameters:
MessageType
|
The message type of the topic to monitor for publishes. There is no default for this parameter. |
Topic
|
The name of the topic to monitor for publishes. This parameter supports regular expressions. There is no default for this parameter. |
MessageSource |
The source to monitor for publishes. The source of
the message defaults to This parameter also accepts |
Filter |
Sets the filter to apply. Only messages that match this filter will cause the action to run. |
Options |
Sets the options to apply when listening for messages. This action supports any option that would be supported by the subscribe command when not using a bookmark. |
Table 24.10: Parameters for On Publish Message
This module adds the following variables to the AMPS context:
Variable | Description |
---|---|
AMPS_TOPIC |
The topic of the message. |
AMPS_DATA |
The data the message contains. |
AMPS_DATA_LENGTH |
The length of the data that the message contains. |
AMPS_BOOKMARK |
The bookmark associated with this message. |
AMPS_TIMESTAMP |
The time at which the message was processed by AMPS. |
AMPS_CLIENT_NAME |
The name of the client from which the message was published. |
Table 24.11: Context Variables for On Publish Message
Running an Action on OOF Message¶
When a record that previously matched a subscription has been updated so
that the record no longer matches its subscription, AMPS sends an
out-of-focus (OOF) message to let subscribers know that their record no
longer matches the subscription. With amps-action-on-oof-message
,
you can enter a subscription within AMPS and run actions when an OOF
message for that subscription is produced.
This action is treated by the AMPS engine as a subscription from an internal AMPS client. Do not use this action with queue topics. Because this action creates a subscription, using this action with the queue topic will cause the action to lease messages from the queue even though the action does not acknowledge messages. This means that, when used with the queue topic itself, the action will interfere with other subscribers and, depending on the queue configuration, may only receive one message during the lifetime of the instance. Furthermore, because each publish to a queue topic is treated
as a distinct message, a subscription to a queue topic
will never produce |
This module requires the following parameters:
Parameter | Description |
---|---|
MessageType
|
The message type of the topic to monitor for OOF messages. This parameter supports regular expressions. There is no default for this parameter. |
Topic
|
The topic to monitor for OOF messages.The topic specified must be a SOW topic, view, or conflated topic. This parameter supports regular expressions. There is no default for this parameter. This module should not be used with queue topics. |
Filter |
Set the filter to apply. This filter forms the internal subscription for which OOF messages will be generated. |
Type |
The type of OOF message to take action on.
Defaults to |
Table 24.12: Parameters for On OOF Message
This module adds the following variables to the AMPS context:
Variable | Description |
---|---|
AMPS_TOPIC |
The topic of the OOF message. |
AMPS_DATA |
The data of the OOF message. |
AMPS_DATA_LENGTH |
The length of the data of the OOF message. |
AMPS_PREVIOUS_DATA |
The data previously contained from the updated record. |
AMPS_PREVIOUS_DATA_LENGTH |
The length of the data previously contained from the updated record. |
Table 24.13: Context Variables for On OOF Message
Running an Action on Minidump¶
AMPS provides the amps-action-on-minidump
module for running actions
when AMPS generates a minidump.
This module does not require parameters.
This module adds the following variable to the AMPS context:
Variable | Description |
---|---|
AMPS_MINIDUMP_PATH |
The path to where the minidump is created. |
Table 24.14: Context Variable for On Minidump
Running an Action on Offline Start or Stop¶
AMPS provides modules to run actions when an AMPS client is marked as a slow client, and also for when the AMPS client catches up to no longer be subject to slow client offlining.
Slow client offlining is a feature in AMPS that reduces the memory resources consumed by slow clients. More on this feature can be found in Slow Client Management.
The amps-action-on-offline-start
module runs actions as the first
step when AMPS’s result set reaches its disk limit and has to disconnect
the client. The amps-action-on-offline-stop
module runs actions as
AMPS is no longer subject to slow client offlining.
In both cases, actions run in the order that the actions appear in the configuration file.
Both modules do not require any parameters.
Both modules add the following variables to the AMPS context:
Variable | Description |
---|---|
AMPS_CLIENT_NAME |
The name of the AMPS client. |
AMPS_CONNECTION_NAME |
The name of the AMPS connection. |
Table 24.15: Context Variables for On Offline Start and Stop
Running an Action on SOW Message Deletion¶
AMPS provides a module to run an action when a message is deleted from a topic in the SOW.
The amps-action-on-sow-delete-message
module monitors a topic for
deletions from the SOW. The action runs once for each message that is
deleted in the matching topic.
Parameter | Description |
---|---|
MessageType
|
The message type of the topic to monitor for messages. There is no default for this parameter. |
Topic
|
The name of the topic to monitor for messages. This parameter does not support regular expressions. The topic name must be one of the topics in the SOW (either a topic in the SOW, a view, a conflated topic, or a queue). There is no default for this parameter. |
Table 24.16: Parameters for On SOW Message Deletion
The module adds the following variables to the AMPS context:
Variable | Description |
---|---|
AMPS_TOPIC |
The topic of the message that expired 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_CORRELATION_ID |
The correlation id set on the publish command, if one was set. |
Table 24.17: Context Variables for On SOW Message Delete
Running an Action on SOW Message Expiration¶
AMPS provides a module to run an action when a message expires from a topic in the SOW.
The amps-action-on-sow-expire-message
module monitors a topic for
expirations. The action runs once for each message that expires in the
matching topic. Notice, in particular, that this includes monitoring
messages that expire from the queue, which are presented as SOW
expirations to this module.
Variable | Description |
---|---|
MessageType
|
The message type of the topic to monitor for messages. There is no default for this parameter. |
Topic
|
The name of the topic to monitor for messages. This parameter does not support regular expressions. The topic name must be one of the topics in the SOW (either a topic in the SOW, a view, a conflated topic, or a queue). There is no default for this parameter. |
Reason |
An optional comma-delimited string indicating the
expiration reasons to monitor for. For example,
setting this to time_limit,forced_expire will
cause this action to be invoked only when the
expiration reason includes one of time_limit or
forced_expire . For more information on the
allowed values and definitions, see the
documentation for AMPS_REASON below. |
Table 24.18: Parameters for On SOW Message Expiration
The module adds the following variables to the AMPS context:
Variable | Description |
---|---|
AMPS_TOPIC |
The topic of the message that expired 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_REASON |
A comma-delimited string indicating one or more reason(s) the message was expired. This string contains one or more of the following values:
|
AMPS_CORRELATION_ID |
The correlation id set on the publish command if one was set. |
Table 24.19: Context Variables for On SOW Message Expire
Running an Action on Message State Change¶
AMPS provides two modules to run an action when a message in a SOW topic meets a specific condition for longer than a specified period of time. This module provides 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 other module, amps-action-on-message-condition-timeout
tracks a message for timeout purposes, but does not trigger an
event if the message is no longer being tracked. Use that module
to keep track of timeouts. Use this module if both conditions
are important. Use amps-action-on-message-condition-timeout
if only timeouts are important.
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)
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 module initializes on restart. |
MessageType
|
The message type of the topic to monitor for messages. There is no default for this parameter. |
Topic
|
The name of the topic to monitor for messages. This parameter does not support regular expressions. The topic name must be one of the topics in the SOW (either a topic in the SOW, a view, or a conflated topic). Queues are not supported. There is no default for this parameter. |
OOFEvent
|
The value to store when an out-of-focus notification is received for a tracked message. There is no default for this parameter. |
TimeoutEvent
|
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
|
The name of the context variable in which to store
the reason that the action is running (either the
string in 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. |
Table 24.20: Parameters for On Alert
The module adds the following variables to the AMPS context:
Variable | Description |
---|---|
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. |
Table 24.21: Context Variables for On Alert
Running an Action on Message Condition Timeout¶
AMPS provides a module to run an action when a message in a SOW topic
meets a specific condition for longer than a specified period of time.
For example, an action might be configured to publish a message to an
Alerts
topic if an order is unprocessed for more than a specified
timeout.
AMPS also provides a module, amps-action-on-alert
, that runs
when either a message has been in a specific condition for a
longer than expected period of time, or the module receives an
out-of-focus notification indicating that the message no longer
meets the tracking condition. Use that module if both
conditions are important. Use this module if it is only important
to track timeouts.
The amps-action-on-message-condition-timeout
monitors a SOW topic
for messages that match a filter and triggers an action for each message
that remains matched on that filter for at least the specified duration.
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.
The module tracks each message that matches the filter individually, and will run once for each message that exceeds the timeout.
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 module initializes on restart. |
MessageType
|
The message type of the topic to monitor for messages. There is no default for this parameter. |
Topic
|
The name of the topic to monitor for messages. This parameter does not support regular expressions. The topic name must be one of the topics in the SOW (either a topic in the SOW, a view, or a conflated topic). Queues are not supported. 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. |
Table 24.22: Parameters for On Message Condition Timeout
The module adds the following variables to the AMPS context:
Variable | Description |
---|---|
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. |
Table 24.23: Context Variables for On Message Condition Timeout
Running an Action on a Custom Event¶
The AMPS action system provides a way to create custom events and run an
action when the custom event is raised. The amps-action-on-execute-event
action runs when a specified custom event is raised by the
amps-action-do-execute-event
action.
This action takes a single parameter:
Parameter | Description |
---|---|
Event
|
The value to watch for. When an event with this name is raised, the action runs. There is no default for this parameter. |
Table 24.24: Parameters for On Execute Event
This module does not add any variables to the AMPS context.
Do Element: Defining the Action to Take¶
This section describes the default modules for specifying what AMPS does when an action runs.
Rotate Log Files¶
AMPS provides the following module for rotating log files. AMPS loads this module by default:
Module Name | Does |
---|---|
amps-action-do-rotate-logs |
Rotates logs that are older than a specified age, for log types that support log rotation. Rotating a log involves closing the log and opening the next log in sequence. AMPS will use the name specifier provided in the AMPS configuration for the new log file. This may overwrite the current log file if the specifier results in the same name as the current log file. |
Table 24.25: Managing Logs
This module does not require options.
This module does not add any variables to the AMPS context.
Manage the Statistics Database¶
AMPS provides the following modules for managing the statistics database. As a maintenance strategy, 60East recommends truncating statistics on a regular basis. This frees space in the database file, which will be reused as new statistics are generated. It is generally not necessary to vacuum statistics unless you have changed your retention policy so that less data is retained between truncation operations. With regular truncation, the statistics database file will usually stabilize at the correct size to hold the amount of data your application generates between truncation operations.
AMPS loads these modules by default.
Module Name | Does |
---|---|
amps-action-do-truncate-statistics |
Removes statistics that are older than a specified age. This frees space in the statistics file, but does not reduce the size of the file. |
amps-action-do-vacuum-statistics |
Remove unused space in the statistics file to reduce the size of the file. In general, it is not necessary to remove unused space in the statistics file. This operation can be expensive, and query access to the statistics database can be unavailable for an extended period of time if the file is large. If storage space is in high demand, and the interval at which the file is vacuumed has been reduced, removing space from the file can sometimes reduce the space needs. 60East recommends using this action only in long-running AMPS environments where space is at a premium, and scheduling the action during times when it is acceptable for monitoring of the system to be unavailable while the file is processed. |
Table 24.26: Managing Statistics
The amps-action-do-truncate-statistics
module requires an Age
parameter that specifies the age of the statistics to process.
Parameter | Description |
---|---|
Age
|
Specifies the age of the statistics to remove. The
module processes any file older than the specified
There is no default for this parameter. |
Table 24.27: Parameters for Managing Statistics
These modules do not add any variables to the AMPS context.
Manage Journal Files¶
AMPS provides the following modules for managing journal files. AMPS loads these modules by default:
Module Name | Does |
---|---|
amps-action-do-archive-journal |
Archives journal files that are older than a specified age to
the JournalArchiveDirectory specified for the transaction
log. |
amps-action-do-compress-journal |
Compresses journal files that are older than a specified age. |
amps-action-do-remove-journal |
Deletes journal files that are older than a specified age. |
Table 24.28: Managing Journals
Each of these modules requires an Age
parameter that specifies the age of the journal files to process.
AMPS will only remove journal files that are no longer needed by the instance. AMPS ensures that all replays from a journal file are complete, all queue messages in that journal file have been delivered (and acknowledged, if required), and all messages from a journal file have been successfully replicated before removing the file.
Journal files that have been compressed or archived (or both) are still part of the transaction log. AMPS will compress and archive journal files that have undelivered queue messages, or that have not yet been fully replicated, and so on.
Parameter | Description |
---|---|
Age
|
Specifies the age of files to process. The module
processes any file older than the specified AMPS does not remove the current journal file, or
files that are being used for replay, files that are
being used for replication, or files that contain
unacknowledged and unexpired messages in a queue;
even if the file is older than the AMPS does not allow gaps in the journal files, so it will only remove a given file if all previous files have been removed. AMPS can compress and archive journal files that are still in use, since compresssed or archived journal files are part of the transaction log and AMPS will replay messages from these files. There is no default for this parameter. |
Table 24.29: Parameters for Managing Journals
These modules do not add any variables to the AMPS context.
Compressing Files¶
AMPS provides the following module for compressing files. Use this action to compress error log files that are no longer needed. AMPS loads this module by default. This action cannot be used to safely compress journal files (also known as transaction log files). For those files, use the journal management actions described in Manage Journal Files.
This action compresses files that match an arbitrary pattern. If the pattern is not specified carefully, this action can compress files that contain important data, are required for AMPS, or are required by the operating system. |
This action cannot be used to safely compress journal files. Use the actions in Manage Journal to manage journal files. |
Module Name | Does |
---|---|
amps-action-do-compress-files |
Compresses files that match the specified pattern that are older than the specified age. This action accepts an arbitrary pattern, and removes files that match that pattern. While AMPS attempts to protect against deleting journal files, using a pattern that removes files that are critical for AMPS, for the application, or for the operating system may result in loss of data. The module does not recurse into directories. It skips open
files. The module does not compress AMPS journals (that is,
files that end with a The commands to remove files are executed with the current permissions of the AMPS process. |
Table 24.30: Compressing Files
This module requires an Age
parameter that specifies the age of the
files to remove, as determined by the update to the file. This module
also requires a Pattern
parameter that specifies a pattern for
locating files to remove.
Parameter | Description |
---|---|
Age
|
Specifies the age of files to process. The module
removes any file older than the specified There is no default for this parameter. |
Pattern
|
Specifies the pattern for files to remove. The
module removes any files that match the specified
This parameter is interpreted as a Unix shell globbing pattern. It is not interpreted as a regular expression. As with other parameters that use the file system, when the pattern specified is a relative path the parameter is interpreted relative to the current working directory of the AMPS process. When the pattern specified is an absolute path, AMPS uses the absolute path. There is no default for this parameter. |
Keep |
Specifies the number of files that meet the Age and Pattern criteria to leave uncompressed. When this parameter is specified, AMPS will compress files matching the criteria, starting with the oldest files, and stop when the number of remaining files is the number specified in this parameter. There is no default for this parameter. When both
|
Count |
Specifies the maximum number of files that meet the
There is no default for this parameter. When both
|
Table 24.31: Parameters for Compressing Files
This module does not add any variables to the AMPS context.
Removing Files¶
AMPS provides the following module for removing files. Use this action to remove error log files that are no longer needed. AMPS loads this module by default. This action cannot be used to safely remove journal files (also known as transaction log files). For those files, use the journal management actions described in Manage Journal Files.
This action removes files that match an arbitrary pattern. If the pattern is not specified carefully, this action can remove files that contain important data, are required for AMPS, or are required by the operating system. |
This action cannot be used to safely remove journal files. Use the actions in Manage Journal to manage journal files. |
Module Name | Does |
---|---|
amps-action-do-remove-files |
Removes files that match the specified pattern that are older than the specified age. This action accepts an arbitrary pattern, and removes files that match that pattern. While AMPS attempts to protect against deleting journal files, using a pattern that removes files that are critical for AMPS, for the application, or for the operating system may result in loss of data. The module does not recurse into directories. It skips open
files. The module does not remove AMPS journals (that is, files
that end with a The commands to remove files are executed with the current permissions of the AMPS process. |
Table 24.32: Removing Files
This module requires an Age
parameter that specifies the age of the
files to remove, as determined by the update to the file. This module
also requires a Pattern
parameter that specifies a pattern for
locating files to remove.
Parameter | Description |
---|---|
Age
|
Specifies the age of files to process. The module
removes any file older than the specified There is no default for this parameter. |
Pattern
|
Specifies the pattern for files to remove. The
module removes any files that match the specified
This parameter is interpreted as a Unix shell globbing pattern. It is not interpreted as a regular expression. As with other parameters that use the file system, when the pattern specified is a relative path the parameter is interpreted relative to the current working directory of the AMPS process. When the pattern specified is an absolute path, AMPS uses the absolute path. There is no default for this parameter. |
Keep |
Specifies the number of files that meet the Age and Pattern criteria to retain. When this parameter is specified, AMPS will remove files matching the criteria, starting with the oldest files, and stop when the number of remaining files is the number specified in this parameter. There is no default for this parameter. When both
|
Count |
Specifies the maximum number of files that meet the
There is no default for this parameter. When both
|
Table 24.33: Parameters for Removing Files
This module does not add any variables to the AMPS context.
Deleting Messages from SOW¶
AMPS also provides modules for deleting SOW contents. The
amps-action-do-delete-sow
module deletes messages from the specified
SOW topic.
This module requires the MessageType
, Topic
, and Filter
parameters in order to delete the desired message.
Parameter | Description |
---|---|
MessageType
|
The MessageType of the SOW topic or topics to delete from. There is no default for this parameter. |
Topic
|
The name of the SOW topic from which to delete messages. This parameter supports regular expressions. There is no default for this parameter. |
Filter
|
Set the filter to apply. Only messages matching that filter will be deleted. |
Table 24.34: Parameters for Deleting SOW Messages
This module does not add any variables to the AMPS context.
Compacting a SOW File¶
AMPS also provides a module for reducing the unused space in a
SOW file. The amps-action-do-compact-sow
module rearranges the
messages in the SOW into a smaller amount of space, where possible.
This module can compact a specific SOW file, or the SOW files for every
topic in the instance. When a MessageType
and Topic
are
provided, this module compacts the SOW file for that topic. Otherwise,
the module compacts the file for all topics in the SOW.
While messages are being added or updated within a topic in the SOW, AMPS reuses free space as possible: it is not necessary to compact the SOW file during most normal operation. This action is most useful after an activity peak that leaves a large amount of unneeded space in the file, or in installations where space is at a premium. Depending on the file size, the number of topics to be compacted, and the amount of free space, the reorganization that this operation performs may require a noticeable amount of I/O bandwidth. 60East recommends that this action run during a maintenance window or in response to a critical lack of disk space.
Parameter | Description |
---|---|
MessageType |
The MessageType of the SOW topic or topics to
compact. This option must be specified if the
There is no default for this parameter. |
Topic |
The name of the SOW topic from which to compact.
This option must be specified if the
There is no default for this parameter. |
Table 24.35: Parameters for Deleting SOW Messages
This module does not add any variables to the AMPS context.
Querying a SOW Topic¶
AMPS provides a module for querying a SOW topic. The
amps-action-do-query-sow
queries the SOW topic, and stores the first
message returned by the SOW query into a user-defined variable.
This module requires the MessageType
, Topic
, and Filter
parameters to identify the query to run. This module requires the
CaptureData
parameter in order to be able to store the result of the
query.
Parameter | Description |
---|---|
MessageType
|
The message type of the topic to query. There is no default for this parameter |
Topic
|
The name of the topic to query. This topic must be a SOW topic, a view, a queue, or a conflated topic. There is no default for this parameter. This parameter supports regular expressions. |
Filter
|
Set the filter to apply. If a Filter is present,
only messages matching that filter will be returned
by the query. |
CaptureData
|
Sets the name of the variable within which AMPS will store the first message returned. |
DefaultData |
If no records are found, AMPS stores the
DefaultData in the variable specified by
CaptureData . |
OrderBy |
An OrderBy expression to use to order the
results returned by the query. For example, to order
in descending order of the /date field in the
messages, you would provide an OrderBy option of
/date DESC . |
Table 24.36: Parameters for Querying SOW Messages
Once you query messages from the SOW topic, you can use the captured
data in other actions. The example below uses
amps-action-do-query-sow
to query the SOW on a schedule in order to
echo messages to the log for diagnostic purposes:
<Actions>
<Action>
<On>
<Module>amps-action-on-schedule</Module>
<Options>
<Every>Saturday at 23:59</Every>
<Name>Diagnostic_Schedule</Name>
</Options>
</On>
<Do>
<Module>amps-action-do-query-sow</Module>
<Options>
<MessageType>xml</MessageType>
<Topic>SOW_TOPIC</Topic>
<Filter>/Trans/Order/@Oname = 'PURCHASE'</Filter>
<CaptureData>AMPS_DATA</CaptureData>
</Options>
</Do>
<Do>
<Module>amps-action-do-extract-values</Module>
<Options>
<MessageType>xml</MessageType>
<Data>{{AMPS_DATA}}</Data>
<Value>SAVED_VARIABLE=/Value</Value>
</Options>
</Do>
<Do>
<Module>amps-action-do-echo-message</Module>
<Options>
<Message>{{SAVED_VARIABLE}} was in the message</Message>
</Options>
</Do>
</Action>
</Actions>
Manage Security¶
AMPS provides modules for managing the security features of an instance.
Authentication and entitlement can be enabled or disabled, which is useful for debugging or auditing purposes. You can also reset security and authentication, which clears the AMPS internal caches and gives security and authentication modules the opportunity to reinitialize themselves, for example, by re-parsing an entitlements file.
AMPS loads the following modules by default:
Module Name | Does |
---|---|
amps-action-do-disable-authentication |
Disables authentication for the instance. |
amps-action-do-disable-entitlement |
Disables entitlement for the instance. |
amps-action-do-enable-authentication |
Enables authentication for the instance. |
amps-action-do-enable-entitlement |
Enables entitlement for the instance. |
amps-action-do-reset-authentication |
Resets authentication by clearing AMPS caches and reinitializing authentication |
amps-action-do-reset-entitlement |
Resets entitlement by clearing AMPS caches and reinitializing entitlement |
Table 24.37: Security Modules
These modules require no parameters. The
amps-action-do-reset-authentication
module and the
amps-action-do-reset-entitlement
module accept an optional
Transport
parameter which specifies the transport to reset.
Parameter | Description |
---|---|
Transport |
The If no |
AuthenticationId |
The If no id is provided, these modules affect all clients. |
Table 24.38: Parameters for Reset Authentication or Entitlement
These modules do not add any variables to the AMPS context.
Enable and Disable a Transport¶
AMPS provides modules that can enable and disable specific transports.
The amps-action-do-enable-transport
module enables a transport. The
amps-action-do-disable-transport
module disables a transport.
Module Name | Does |
---|---|
amps-action-do-enable-transport |
Enables a specific transport. |
amps-action-do-disable-transport |
Disables a specific transport. |
Table 24.39: Transport Action Modules
Both modules require the name of the transport to disable or enable.
Parameter | Description |
---|---|
Transport |
The If no |
Table 24.40: Parameters for Managing Transports
Both modules do not add any variables to the AMPS context.
Publishing Messages¶
The amps-action-do-publish-message
module publishes a message into a
specified topic.
Publishes from this action are treated as publishes from an AMPS client inside the AMPS engine. This means that:
- There are no user credentials associated with the publish, so entitlements are not applied.
- There is no special handling for the publish. The publish is recorded in the transaction log exactly as if it arrived from outside of the instance, and is processed within the instance as if the had arrived from an external publisher.
This action is treated by the AMPS engine as a publish from an
internal AMPS client.When an This warning includes cases where the action publishes to a
topic directly monitored by the action, cases where the action
monitors a view and publishes to an underlying topic of the
view. The warning also applies to configurations in which two or
more actions “cross publish” to topics that are monitored by the
other action. An example of the last case is an action that
monitors The result of a configuration like the ones described above is called a publish loop. AMPS does not support unterminated publish loops or loops that produce a large number of cycles before terminating. |
To publish a message, this module requires the MessageType
, a
Topic
to publish on, and also the Data
that the message will
contain.
Parameter | Description |
---|---|
MessageType
|
The MessageType for the topic. There is no default for this parameter. |
Topic
|
The topic of the message being published. |
Data |
The data that the message will contain. |
Delta |
Whether to use a delta publish. When this option is
present, and the value is true , the action will
use a delta publish. |
UpdateOnly |
Specifies whether a delta publish is allowed to insert
a record, or only update a record. When a delta publish
is specified (that is, When no value is specified, this option is |
Table 24.41: Parameters for Publishing Messages
This action is treated by the AMPS engine as a publish from an
internal AMPS client.When an This includes both cases where the action publishes to a topic directly monitored by the action, cases where the action monitors a view and publishes to an underlying topic of the view, and cases where two or more actions each publish to a topic that is monitored by another action. In effect, a configuration like the one described above creates a recursive call to the action: that recursion must terminate, and must terminate at a relatively low depth. (The exact limits depend on system capacity, message size, and so on). |
This module does not add any variables to the AMPS context.
Manage Replication¶
AMPS provides modules for downgrading replication destinations that fall behind and upgrading them again when they catch up.
Module Name | Does |
---|---|
amps-action-do-downgrade-replication |
Downgrades replication connections from synchronous to asynchronous if the age of the last acknowledged message is older than a specified time period. |
amps-action-do-upgrade-replication |
Upgrades previously-downgraded
replication connections from
asynchronous to synchronous if the age
of the last acknowledged message is
more recent than a specified time
period. This action has no effect on
replication destinations that are
specified as async in the
configuration file. |
Table 24.42: Replication Modules
The modules determine when to downgrade and upgrade based on the age of
the oldest message that a destination has not yet acknowledged. When
using these modules, it is important that the thresholds for the modules
are not set too close together. Otherwise, AMPS may repeatedly upgrade
and downgrade the connection when the destination is consistently
acknowledging messages at a rate close to the threshold values. To avoid
this, 60East recommends that the Age
set for the upgrade module is
1/2 of the age used for the downgrade module.
The amps-action-do-downgrade-replication
module accepts the
following options:
Parameter | Description |
---|---|
Age
|
Specifies the maximum message age at which AMPS
downgrades a replication destination to For example, when the There is no default for this parameter. |
GracePeriod |
The approximate time to wait after start up before
beginning to check whether to downgrade links. The
GracePeriod allows time for other AMPS instances
to start up, and for connections to be established
between AMPS instances. |
Table 24.43: Parameters for Downgrading Replication
The amps-action-do-upgrade-replication
module only applies to
destinations configured as sync
that have been previously
downgraded. The module accepts the following options:
Parameter | Description |
---|---|
Age
|
Specifies the maximum message age at which a
previously-downgraded destination will be upgraded
to For example, if a destination has been downgraded to
There is no default for this parameter. |
GracePeriod |
The approximate time to wait after start up before
beginning to check whether to upgrade links. The
GracePeriod allows time for other AMPS instances
to start up, and for connections to be established
between AMPS instances. |
Table 24.44: Parameters for Upgrading Replication
These modules do not add any variables to the AMPS context.
Extract Values¶
The amps-action-do-extract-values
module extracts message values
from a message and stores the values in a variable.
To extract values from a message, this module requires the
MessageType
, Data
, and Value
parameters.
Parameter | Description |
---|---|
MessageType
|
The MessageType for the message to parse. There is no default for this parameter. |
Data |
Contains the data to parse: typically a message received from a publish event or retrieved from a SOW query. There is no default value for this parameter. If it is omitted, AMPS will not parse data when the action is run. |
Value |
An assignment statement that specifies the variable
to store the extracted value in and the XPath
identifier for the value to extract. This action can
contain any number of The format of the assignment is as follows: variable=amps-expression
For example, the following assignment statement stores
the value of the PREVIOUS_REGION=/previousRegionCode
Likewise, the following assignment statement creates a string from the values
of the COMBINED_NAME=CONCAT(/firstName, ' ', /lastName)
There is no default for this option. If no |
Table 24.45: Parameters for Extract Values
The module amps-action-do-extract-values
adds the variables
specified by the Value
options to the current context.
Translate Data¶
The amps-action-do-translate-data
action allows you to translate the
value from variables in the current context. One common use for this
action is to translate a large number of status values into a smaller
number of states before publishing that information in a message. For
example, an order processing system may track a large number of
finely-grained status codes, while the reporting view for customers may
want to map those status codes to a smaller set of codes such as
“pending”, “shipped”, and “delivered”. This action allows you to easily
translate those codes within AMPS.
When used to assemble a message, this action provides equivalent results to a set of nested conditional statements in a view projection. However, if you are using actions to parse, assemble, and publish messages, this action gives you the ability to change values.
Parameter | Description |
---|---|
Data
|
The data to translate. Most often, this is the value of a variable in the current context. |
Value
|
The variable to store the translated value in. |
Case |
A translation statement. The translation statement
takes the form of The action matches the For example, the following translation statement
translates a value of <Case>credit_check_in_progress=pending</Case>
There is no default for this option. |
Default |
The default translation. AMPS sets the value of the variable to the contents of this element if no Case statement matches the Data provided. This element is optional. If no |
Table 24.46: Parameters for Translate Data
Increment Counter¶
The amps-action-do-increment-counter
module allows AMPS to increment
a counter by a value. Counters persist across action runs, and are saved
in the instance memory until the instance is restarted.
If a counter with the specified name does not currently exist in the instance when the action runs, AMPS creates the counter with a value of 0 and then immediately increments it with the specified value. If the counter is already present, AMPS will simply increment the counter.
To see an example of amps-action-do-increment-counter
, refer to the
Action Configuration Examples section at the end of this chapter.
This module requires a Key
that tells AMPS which counter to
increment and a Value
that tells AMPS where to store the incremented
value.
Parameter | Description |
---|---|
Key
|
The name of the counter that AMPS will increment. There is no default value for this parameter. |
Value
|
The variable in which to store the current value of the counter. |
Table 24.47: Parameter for Increment Counter
This module adds variable that contains the counter, as specified in the
Value
parameter, to the current context.
Raising a Custom Event¶
The AMPS action system provides a way to create custom events and run an
action when the custom event is raised. A custom event is raised by
the amps-action-do-execute-event
action. Events are received
by the amps-action-on-execute-event
module.
This action requires one of the following parameters:
Parameter | Description |
---|---|
Event
|
The name of the event to raise. There is no default value for this parameter. |
EventVariable
|
The variable from which to retrieve the name of the event to raise. There is no default value for this parameter. |
Table 24.48: Parameters for Do Execute Event
This module does not add any variables to the AMPS context.
Executing System Commands¶
The amps-action-do-execute-system
module allows AMPS to execute
system commands.
The parameter for this module is simply the command. The command executes in the current working directory of the AMPS process, with the credentials and environment of the AMPS process.
The thread used to execute the command is monitored by AMPS thread monitoring. This means that the command must complete within a short period of time (on the order of a second or two at the longest) or AMPS may consider the thread to have become deadlocked.
Parameter | Description |
---|---|
Command |
The command to execute. When the action runs, this command is executed as a shell command on the system where AMPS is running. |
Table 24.49: Parameter for Execute System
This module does not add any variables to the AMPS context.
This module executes system commands with the credentials of the AMPS process. It is possible to damage the system, interrupt the AMPS service, or cause data loss by executing commands with this module. 60East recommends against using any data extracted from an AMPS message in the command executed. |
Debugging Actions¶
AMPS provides modules for debugging your AMPS action configuration.
Module Name | Does |
---|---|
amps-action-do-nothing |
Takes no action. Does not modify the state of AMPS in any way. The module simply logs that it was called. |
amps-action-do-echo-message |
Echoes the specified message to the log. The message appears in
the log as message 29-0103 ,at info level.The logging
configuration must allow this message to be recorded for the
output of this action to appear in the log. |
Table 24.50: Debugging Modules
The amps-action-do-nothing
module requires no parameters.
The amps-action-do-echo-message
module requires the following
parameter:
Parameter | Description |
---|---|
Message |
The message to echo. The default for this parameter is simply an empty string. |
Table 24.51: Parameter for Echo Message
These modules do not add any variables to the AMPS context.
Creating a Minidump¶
AMPS provides a module for creating a minidumps. The
amps-action-do-minidump
module provides a way for developers and/or
administrators to easily create minidumps for diagnostic purposes.
Module Name | Does |
---|---|
amps-action-do-minidump |
Creates a minidump. |
Table 24.52: Creating a Minidump Module
This module does not require any parameters.
This module does not add any variables to the AMPS context.
Shut Down AMPS¶
The amps-action-do-shutdown
module shuts down AMPS. This module is
registered as the default action for several Linux signals, as described
in Default Signal Actions.
Module Name | Does |
---|---|
amps-action-do-shutdown |
Shuts down AMPS. |
Table 24.53: Shut Down Module
This module does not require any parameters.
This module does not add any variables to the AMPS context.
If Element: Conditionally Stop Action Sequence¶
AMPS includes the ability to run actions only if certain conditions are
true. For some actions (such as the replication management actions), the
condition is included as a part of the action. In other cases, AMPS
provides If
actions.
An If
action is evaluated each time the execution of an action
reaches the If
action. When the condition specified in an If
action is true
, AMPS proceeds to the next Do
action. If the
condition in an If
action is False
, AMPS does not run any
further Do
elements in the action.
File System Usage¶
AMPS provides the following If
module for taking action based on the
file system capacity. AMPS loads this module by default:
Module Name | Does |
---|---|
amps-action-if-file-system-usage |
Checks whether the specified path on the filesystem meets the specified usage level. If so, allows execution to continue. If not, stops the action. |
Table 24.54: File System Usage
Parameter | Description |
---|---|
Path
|
Specifies the filesystem path to monitor. The AMPS process must have sufficient permissions to check the disk usage for this path at the time the check runs. There is no default for this parameter. |
GreaterThan
|
The threshold to check, specified as a percentage.
If the provided path has more space used than
specified in this parameter, subsequent Do and
If blocks will run. Otherwise, the action will
complete with this step. |
Table 24.55: Parameters for Running Actions Based on File System Usage
This module does not add any variables to the AMPS context.
For example, the following action will log a message in the AMPS log every minute when the file system becomes more than 90% full, and perform a full shutdown of AMPS if the file system is more than 98% full.
<Actions>
<Action>
<On>
<Module>amps-action-on-schedule</Module>
<Options>
<Every>1m</Every>
</Options>
</On>
<If>
<Module>amps-action-if-file-system-usage</Module>
<Options>
<GreaterThan>90%</GreaterThan>
<Path>/mnt/fastdrive/amps</Path>
</Options>
</If>
<Do>
<Module>amps-action-do-echo-message</Module>
<Options>
<Message>ALERT: You're getting low on space!</Message>
</Options>
</Do>
<If>
<Module>amps-action-if-file-system-usage</Module>
<Options>
<GreaterThan>98%</GreaterThan>
<Path>/mnt/fastdrive/amps</Path>
</Options>
</If>
<Do>
<Module>amps-action-do-echo-message</Module>
<Options>
<Message>CRITICAL: Shutting down AMPS</Message>
</Options>
</Do>
<Do>
<Module>amps-action-do-shutdown</Module>
</Do>
</Action>
</Actions>
Action Configuration Examples¶
Archive Transaction Log Journal Files Older Than One Week, Every Saturday¶
The listing below asks AMPS to archive transaction log journal files older than 1 week, every Saturday at 12:30 AM.
This configuration moves journal files from the JournalDirectory to the JournalArchiveDirectory, while maintaining the files as an active part of the transaction log (ensuring that they are still available for bookmark replay, replication, and so on):
<Actions>
<Action>
<On>
<Module>amps-action-on-schedule</Module>
<Options>
<Every>Saturday at 00:30</Every>
<Name>Saturday Night Fever</Name>
</Options>
</On>
<Do>
<Module>amps-action-do-archive-journal</Module>
<Options>
<Age>7d</Age>
</Options>
</Do>
</Action>
</Actions>
Disable and Re-enable Security on Signal¶
The listing below disables authentication and entitlement when AMPS
receives on the USR1
signal. When AMPS receives the USR2
signal,
AMPS re-enables authentication and entitlement. This configuration is,
in effect, the configuration that AMPS installs by default for these
signals:
<Actions>
<Action>
<On>
<Module>amps-action-on-signal</Module>
<Options>
<Signal>SIGUSR1</Signal>
</Options>
</On>
<Do>
<Module>amps-action-do-disable-authentication</Module>
</Do>
<Do>
<Module>amps-action-do-disable-entitlement</Module>
</Do>
</Action>
<Action>
<On>
<Module>amps-action-on-signal</Module>
<Options>
<Signal>SIGUSR2</Signal>
</Options>
</On>
<Do>
<Module>amps-action-do-enable-authentication</Module>
</Do>
<Do>
<Module>amps-action-do-enable-entitlement</Module>
</Do>
</Action>
</Actions>
Reset entitlements for a disconnected client¶
The listing below resets entitlement cache for a client when the client is disconnected:
<Actions>
<Action>
<On>
<Module>amps-action-on-disconnect-client</Module>
</On>
<Do>
<Module>amps-action-do-reset-entitlement</Module>
<Options>
<AuthenticationId>{{AMPS_AUTHENTICATION_ID}}</AuthenticationId>
</Options>
</Do>
</Action>
</Actions>
Extract Values on Publish of a Message¶
The listing below extracts values from a locally published xml message and stores them into VALUE.
<Actions>
<Action>
<On>
<Module>amps-action-on-publish-message</Module>
<Options>
<Topic>message-sow</Topic>
<MessageType>xml</MessageType>
<MessageSource>local</MessageSource>
</Options>
</On>
<Do>
<Module>amps-action-do-extract-values</Module>
<Options>
<MessageType>xml</MessageType>
<Data>{{AMPS_DATA}}</Data>
<Value>VALUE = /VALUE</Value>
</Options>
</Do>
</Action>
</Actions>
Increment a Counter and Echo a Message on Signal¶
The listing below increments a counter and echoes the counter’s value
when AMPS receives on the USR1
signal.
<Actions>
<Action>
<On>
<Module>amps-action-on-signal</Module>
<Options>
<Signal>SIGUSR1</Signal>
</Options>
</On>
<Do>
<Module>amps-action-do-increment-counter</Module>
<Options>
<Key>MY_COUNTER</Key>
<Value>CURRENT_COUNTER_VALUE</Value>
</Options>
</Do>
<Do>
<Module>amps-action-do-echo-message</Module>
<Options>
<Message>AMPS has gotten {{CURRENT_COUNTER_VALUE}}
SIGUSR1 signals.</Message>
</Options>
</Do>
</Action>
</Actions>
Recording Expired Queue Messages in a Dead Letter Topic¶
The listing below detects when a message expires from a queue, and publishes those messages to a dead letter topic.
<Actions>
<Action>
<On>
<Module>amps-action-on-sow-expire-message</Module>
<Options>
<Topic>interesting-queue</Topic>
<MessageType>json</MessageType>
</Options>
</On>
<On>
<Module>amps-action-on-sow-expire-message</Module>
<Options>
<Topic>another-interesting-queue</Topic>
<MessageType>json</MessageType>
</Options>
</On>
<Do>
<Module>amps-action-do-publish-message</Module>
<Options>
<Topic>dead-letter</Topic>
<MessageType>json</MessageType>
<Data>{"topic":"{{AMPS_TOPIC}}","message":{{AMPS_DATA}} }</Data>
</Options>
</Do>
</Action>
</Actions>
Copy a Message to a Different Topic When a Timeout is Exceeded¶
The listing below, in effect, copies messages from the Orders
topic
to the Orders_Stale
topic when the status has been PENDING
for
more than 5 seconds.
<Actions>
<Action>
<On>
<Module>amps-action-on-message-condition-timeout</Module>
<Options>
<MessageType>nvfix</MessageType>
<Topic>Orders</Topic>
<Filter>/status = 'PENDING'</Filter>
<Duration>5s</Duration>
</Options>
</On>
<Do>
<Module>amps-action-do-publish-message</Module>
<Options>
<MessageType>nvfix</MessageType>
<Topic>Orders_Stale</Topic>
<Data>{{AMPS_DATA}}</Data>
</Options>
</Do>
</Action>
</Actions>
Shutting Down AMPS When Filesystem Fills¶
The listing below directs AMPS to perform a graceful shutdown when the filesystem becomes full, with a check run every 3 seconds.
<Actions>
<Action>
<On>
<Module>amps-action-on-schedule</Module>
<Options>
<Every>3s</Every>
</Options>
</On>
<If>
<Module>amps-action-if-file-system-usage</Module>
<Options>
<Path>./</Path>
<GreaterThan>99%</GreaterThan>
</Options>
</If>
<Do>
<Module>amps-action-do-shutdown</Module>
</Do>
</Action>
</Actions>