LogoLogo
AMPS Server Documentation 5.3.4
AMPS Server Documentation 5.3.4
  • Welcome to AMPS 5.3.4
  • Introduction to AMPS
    • Overview of AMPS
    • Getting Started With AMPS
      • Installing AMPS
      • Starting AMPS
      • JSON Messages - A Quick Primer
      • spark: the AMPS command-line client
      • Evaluating AMPS on Windows or MacOS
      • Galvanometer and RESTful Statistics
    • AMPS Basics: Subscribe and Publish to Topics
    • State of the World (SOW): The Message Database
      • When Should I Store a Topic in the SOW?
      • How Does the SOW Work?
      • Configuration
      • Queries
      • Atomic Query and Subscribe
      • Advanced Messaging and the SOW
    • Record and Replay Messages with the AMPS Transaction Log
    • Message Queues
    • Scenario and Feature Reference
      • Recovery Strategies
    • Getting Support
    • Advanced Topics
    • Next Steps
  • AMPS Evaluation Guide
    • Introduction
    • Evaluation and Development with AMPS
    • Tips on Measuring Performance
    • Next Steps
  • AMPS User Guide
    • Introduction
      • Product Overview
      • Requirements
      • Organization of this Guide
        • Documentation Conventions
      • Technical Support
    • Installing and Starting AMPS
      • Installing AMPS
      • Starting AMPS
      • Production Configuration
    • Subscribe and Publish
      • Topics
      • Filtering Subscriptions by Content
      • Conflated Subscriptions
      • Replacing Subscriptions
      • Messages in AMPS
      • Message Ordering
      • Retrieving Part of a Message
    • AMPS Expressions
      • Syntax
      • Identifiers
      • AMPS Data Types
      • Grouping and Order of Evaluation
      • Logical Operators
      • Arithmetic Operators
      • Comparison Operators
      • LIKE Operator
      • Conditional Operators
      • Working with Arrays
      • Regular Expressions
      • Performance Considerations
    • AMPS Functions
      • AMPS Function Overview
      • String Comparison Functions
      • Concatenating Strings
      • Managing String Case
      • Replacing Text in Strings
      • String Manipulation Functions
      • Date and Time Functions
      • Array Reduce Functions
      • Geospatial Functions
      • Numeric Functions
      • CRC Functions
      • Message Functions
      • Client Functions
      • Coalesce Function
      • AMPS Information Functions
      • Typed Value Creation
      • Constructing Fields
      • Aggregate Functions
    • State of the World (SOW) Topics
      • How Does the SOW Work?
      • Using the State of the World
      • Understanding SOW Keys
      • Indexing SOW Topics
      • Programmatically Deleting Records from the Topic State
      • SOW Maintenance
        • Creating a Maintenance Schedule for a Topic
        • Setting Per-Message Lifetime
      • Storing Multiple Logical Topics in One Physical Topic
    • Querying the State of the World (SOW)
      • Overview of SOW Queries
      • Query and Subscribe
      • Historical SOW Topic Queries
      • Managing Result Sets
      • Batching Query Results
    • Out-of-Focus Messages (OOF)
    • State of the World Message Enrichment
    • Incremental Message Updates
      • Using Delta Publish
      • Understanding Delta Publish
      • Delta Publish Support
    • Receiving Only Updated Fields
      • Using Delta Subscribe
      • Identifying Changed Records
      • Conflated Subscriptions and Delta Subscribe
      • Select List and Delta Subscribe
      • Options for Delta Subscribe
    • Conflated Topics
    • Aggregation and Analytics
      • Understanding Views
      • Defining Views and Aggregations
      • Constructing Field Contents
      • Best Practices for Views
      • View Examples
      • Aggregated Subscriptions
    • Record and Replay Messages
      • Using the Transaction Log and Bookmark Subscriptions
      • Understanding Message Persistence
      • Configuring a Transaction Log
      • Replaying Messages with Bookmark Subscription
      • Managing Journal Files
      • Using amps-grep to Search the Journal
    • Message Queues
      • Getting Started with AMPS Queues
      • Understanding AMPS Queuing
      • Advanced Messaging and Queues
      • Replacing Queue Subscriptions
      • Handling Unprocessed Messages
      • Advanced Queue Configuration
      • Queue Subscriptions Compared to Bookmark Replays
    • Message Types
      • Default Message Types
      • BFlat Messages
      • MessagePack Messages
      • Composite Messages
      • Protobuf Message Types
      • Struct Message Types
    • Command Acknowledgment
      • Requesting Acknowledgments
      • Receiving Acknowledgments
      • Bookmark Subscriptions and Completed Acknowledgments
      • Bookmark Subscriptions and Persisted Acknowledgments
      • Acknowledgment Conflation and Publish Acknowledgements
    • Transports
      • Client Connections
      • Replication Connections
      • Transport Filters
    • Running AMPS as a Linux Service
      • Installing the Service
      • Configuring the Service
      • Managing the Service
      • Uninstalling the Service
    • Logging
      • Configuring Logging
      • Log Message Format
      • Message Levels
      • Message Categories
      • Logging to a File
      • Logging to a Compressed File
      • Logging to Syslog
      • Logging to the Console
      • Looking up Errors with ampserr
    • Event Topics
      • Client Status Events
      • SOW Statistics Events
      • Persisting Event Topics
    • Utilities
      • Command-Line Basic Client
      • Dump clients.ack File
      • Dump journal File
      • Dump queues.ack File
      • Dump SOW File
      • Dump Journal Topic Index File
      • Find Bookmark or Transaction ID in Transaction Log
      • Find Information in Error Log or Transaction Log
      • Identify Type of AMPS File
      • List/Explain Error Codes
      • Query Statistics Database
      • Statistics Database Report
      • Storage Performance Testing
      • Submit Minidump to 60East
      • Obsolete Utility: Upgrade File Formats
    • Monitoring AMPS
      • Statistics Collection
        • Time Range Selection
        • Output Formatting
      • Galvanometer
      • Configuring Monitoring
    • Automating AMPS with Actions
    • Replicating Messages Between Instances
      • Replication Basics
      • Configuring Replication
      • Replication Configuration Validation
      • Replication Resynchronization
      • Replication Compression
      • Destination Server Failover
      • Two-Way Replication
      • PassThrough Replication
      • Guarantees on Ordering
      • Replication Security
      • Understanding Replication Message Routing
      • Replicated Queues
      • Replication Best Practices
    • Highly Available AMPS Installations
      • Overview of High Availability
        • Example: Pair of Instances for Failover
        • Example: Regional Distribution
        • Example: Regional Distribution with HA
        • Example: Hub and Spoke / Expandable Mesh
      • Details of High Availability
      • Slow Client Management and Capacity Limits
      • Message Ordering Considerations
    • Operation and Deployment
      • Capacity Planning
      • Linux OS Settings
      • Upgrading AMPS
      • Using AMPS with a Proxy
      • Operations Best Practices
    • Securing AMPS
      • Authentication
      • Entitlement
      • Providing an Identity for Outbound Connections
      • Protecting Data in Transit Using TLS/SSL
    • Troubleshooting AMPS
      • Planning for Troubleshooting
      • Diagnostic Utilities
      • Finding Information in the Log
      • Reading Replication Log Messages
      • Troubleshooting Disconnected Clients
      • Troubleshooting Regular Expression Subscriptions
    • AMPS Distribution Layout
    • Optionally-Loaded Modules
      • Optional Functions
        • Legacy Messaging Functions
        • Special-Purpose Functions
      • Optional SOW Key Generator
        • Chaining Key Generator
      • Optional Authentication/Entitlements Modules
        • RESTful Authentication and Entitlements
        • Multimethod Authentication Module
        • Simple Access Entitlements Module
      • Optional Authenticator Modules
        • Multimethod Authenticator
        • Command Execution Authenticator
    • AMPS Statistics
    • File Format Versions
  • AMPS Configuration Guide
    • AMPS Configuration Basics
      • Getting Started With AMPS Configuration
      • Units, Intervals, and Environment Variables
      • Working With Configuration Files
      • Including External Files
    • Instance Level Configuration
    • Admin Server and Statistics
    • Modules
    • Message Types
    • Transports
    • Logging
    • State of the World (SOW)
      • SOW/Topic
      • SOW/*Queue
      • SOW/ConflatedTopic
      • SOW/View
    • Replication
      • Replication Validation
    • Transaction Log
    • Authentication
    • Entitlement
    • Actions
      • Configuration for Actions
      • Choosing When an Action Runs
        • On a Schedule
        • On AMPS Startup or Shutdown
        • On a Linux Signal
        • On a REST Request
        • On Minidump Creation
        • On Client Connect or Disconnect
        • On Client Logon
        • On Client Offline Message Buffering
        • On Subscribe or Unsubscribe
        • On Incoming Replication Connections
        • On Outgoing Replication Connections
        • On Message Published to AMPS
        • On Message Delivered to Subscriber
        • On Message Affinity
        • On SOW Message Expiration
        • On SOW Message Delete
        • On OOF Message
        • On Message Condition Timeout
        • On Message State Change
        • On a Custom Event
      • Choosing What an Action Does
        • Rotate Error/Event Log
        • Compress Files
        • Truncate Statistics
        • Manage Transaction Log Journal Files
        • Remove Files
        • Delete SOW Messages
        • Compact SOW Topic
        • Query SOW Topic
        • Manage Security
        • Enable or Disable Transports
        • Publish Message
        • Manage Replication Acknowledgment
        • Extract Values from a Message
        • Translate Data Within an Action
        • Increment Counter
        • Raise a Custom Event
        • Execute System Command
        • Manage Queue Transfers
        • Create Minidump
        • Shut Down AMPS
        • Debug Action Configuration
      • Conditionally Stopping an Action
        • Based on File System Capacity
        • Based on an Expression
      • Examples of Action Configuration
        • Archive Journals Once a Week
        • Archive Journals On RESTful Command
        • Record Expired Queue Messages to a Dead Letter Topic
        • Copy Messages that Exceed a Timeout to a Different Topic
        • Deactivate and Reactivate Security on Signals
        • Reset Entitlements for a Disconnected Client
        • Extract Values from a Published Message
        • Shut Down AMPS When a Filesystem Is Full
        • Increment a Counter and Echo a Message
    • Protocols
  • AMPS Monitoring Guide
    • Statistics Types
    • Table Reference
    • Administrative Actions
    • Host Statistics
      • cpu
      • disks
      • memory
      • name
      • network
    • AMPS Instance Statistics
      • api
      • clients
      • config.xml
      • config_path
      • conflated_topics
      • cpu
      • cwd
      • description
      • environment
      • lifetimes
      • logging
      • memory
      • message_types
      • name
      • name_hash
      • pid
      • processors
      • queues
      • queries
      • replication
      • sow
      • statistics
      • subscriptions
      • timestamp
      • transaction_log
      • transports
      • tuning
      • uptime
      • user_id
      • version
      • views
  • AMPS Command Reference
    • Commands to AMPS
      • logon
      • Publishing
        • publish
        • delta_publish
      • Subscribing to and Querying Topics
        • subscribe
        • sow
        • sow_and_subscribe
        • unsubscribe
        • delta_subscribe
        • sow_and_delta_subscribe
      • Removing Messages (SOW/Topic or Message Queue)
      • heartbeat
      • flush
    • Responses from AMPS
      • sow: Content from Server
      • publish: Content from Server
      • oof: Content from Server
      • ack: Status from Server
      • group_begin / group_end : Result Set Delimiters
    • Protocol Reference
      • AMPS Protocol
      • Legacy Protocols Reference
    • Command Cookbook
      • Cookbook: Delta Publish
      • Cookbook: Delta Subscribe
      • Cookbook: Publish
      • Cookbook: SOW
      • Cookbook: SOW and Delta Subscribe
      • Cookbook: SOW and Subscribe
      • Cookbook: SOW Delete
      • Cookbook: Subscribe
  • Deployment Checklist
    • Ensure Sufficient Capacity
    • Apply System and AMPS Configuration
    • Create Maintenance Plan
    • Create Monitoring Strategy
    • Create Patch and Upgrade Plan
    • Create and Test Support Process
    • Conclusion
  • AMPS Clients
    • Performance Tips and Best Practices
    • C++
    • C#/.NET
    • Java
    • JavaScript
    • Python
Powered by GitBook

Get Help

  • FAQ
  • Legacy Documentation
  • Support / Contact Us

Get AMPS

  • Evaluate
  • Develop

60East Resources

  • Website
  • Privacy Policy

Copyright 2013-2024 60East Technologies, Inc.

On this page
  • On: Choosing When an Action Runs
  • Do: Choosing What an Action Does
  • Conditionally Stop an Action
  • Examples
Export as PDF
  1. AMPS Configuration Guide

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.

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 following modules by default:

On: Choosing When an Action Runs

The following table lists the On actions that are provided in AMPS by default. Details for each action are provided in the section describing that action.

Condition
Modules

amps-action-on-schedule

amps-action-on-startup amps-action-on-shutdown

amps-action-on-signal

amps-action-on-admin

amps-action-on-minidump

amps-action-on-connect-client amps-action-on-disconnect-client

amps-action-on-logon-client

amps-action-on-offline-start amps-action-on-offline-stop

amps-action-on-subscribe amps-action-on-unsubscribe

amps-action-on-connect-incoming-replication amps-action-on-disconnect-incoming-replication

amps-action-on-connect-replication amps-action-on-disconnect-replication amps-action-on-replication-resync-complete amps-action-on-upgrade-replication amps-action-on-downgrade-replication

amps-action-on-publish-message

amps-action-on-deliver-message

amps-action-on-message-affinity

amps-action-on-sow-expire-message

amps-action-on-sow-delete-message

amps-action-on-oof-message

amps-action-on-message-condition-timeout

amps-action-on-alert

amps-action-on-execute-event

Do: Choosing What an Action Does

The following table lists the Do actions that are provided in AMPS by default. Details for each action are provided in the section describing that action.

Action
Module

amps-action-do-rotate-logs

amps-action-do-compress-files

amps-action-do-truncate-statistics

amps-action-do-archive-journal amps-action-do-compress-journal amps-action-do-remove-journal

amps-action-do-remove-files

amps-action-do-delete-sow

amps-action-do-compact-sow

amps-action-do-query-sow

amps-action-do-disable-authentication amps-action-do-enable-authentication amps-action-do-reset-authentication amps-action-do-reset-entitlement

amps-action-do-disable-entitlement amps-action-do-enable-entitlement

amps-action-do-enable-transport amps-action-do-disable-transport

amps-action-do-publish-message

amps-action-do-downgrade-replication amps-action-do-upgrade-replication

amps-action-do-extract-values

amps-action-do-translate-data

amps-action-do-increment-counter

amps-action-do-execute-event

amps-action-do-execute-system

amps-action-do-enable-proxied-transfer amps-action-do-disable-proxied-transfer

amps-action-do-minidump

amps-action-do-shutdown

amps-action-do-nothing amps-action-do-echo-message

Conditionally Stop an Action

The following table lists the If actions that are provided in AMPS by default. Details for each action are provided in the section describing that action.

Condition
Module

amps-action-if-file-system-usage

amps-action-if-condition

Examples

PreviousEntitlementNextConfiguration for Actions

Last updated 7 months ago

See the configuration section of the AMPS documentation for .

examples of action configuration
On a Schedule
On AMPS Startup or Shutdown
On a Linux Signal
On a REST Request
On Minidump Creation
On Client Connect or Disconnect
On Client Logon
On Client Offline Message Buffering
On Subscribe or Unsubscribe
On Incoming Replication Connections
On Outgoing Replication Connections
On Message Published to AMPS
On Message Delivered to Subscriber
On Message Affinity
On SOW Message Expiration
On SOW Message Delete
On Out-of-Focus Message
On Message Condition Timeout
On Message State Change
On Custom Event
Rotate Error/Event Log
Compress Files
Truncate Statistics
Manage Transaction Log Journal Files
Remove Error/Event Log Files
Delete SOW Messages
Compact SOW Topics
Query a SOW Topic
Manage Security
Enable or Disable Transports
Publish Message
Manage Replication Acknowledgement
Extract Values from a Message
Translate Data Within an Action
Increment Counter
Raise a Custom Event
Execute System Command
Manage Queue Transfers
Create a Minidump
Shutdown AMPS
Debug Action Configurations
Stop Based on File System Capacity
Stop Based on Evaluating an Expression