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
  • State of the World File Name
  • Log Rotation Name
  • Dates
  • Using Units in the Configuration
  • Environment Variables in AMPS Configuration
  • Internal Environment Variables
Export as PDF
  1. AMPS Configuration Guide
  2. AMPS Configuration Basics

Units, Intervals, and Environment Variables

In AMPS there are a few special characters that you should be aware of when creating your configuration file. These characters can provide some handy shortcuts and make configuration creation easier, but you should also be aware of them so as not to introduce errors.

State of the World File Name

When specifying the file for a State of the World database, using the %n string in the file name specifies that the AMPS server will use the message type and topic name in that position to create a unique file name. The example below shows how to use this in the AMPS configuration file.

<SOW>
    <Topic>
        <Topic>Customers</Topic>
        <FileName>./sow/%n.sow</FileName>
        <MessageType>json</MessageType>
        <Key>/customerId</Key>
    </Topic>
</SOW>

Log Rotation Name

When specifying an AMPS log file which has RotationThreshold specified, using the %n string in the log file name is a useful mechanism for ensuring the name of the log file is unique and sequential. The example below shows a file name token replacement in the AMPS configuration file.

<Logging>
    <Target>
        <Protocol>file</Protocol>
        <Level>info</Level>
        <FileName>log/log-%n.log</FileName>
        <RotationThreshold>2G</RotationThreshold>
    </Target>
</Logging>

In the above example, a log file will be created in the AMPSDIR/log/ directory. The first time this file is created, it will be named log-1.log. Once the log file reaches the RotationThreshold limit of 2G, the previous log file will be saved, and the new log file name will be incremented by one. Thus, the next log file will be named AMPSDIR/log/log-2.log.

Dates

AMPS allows administrators to use date based file names when specifying the file name in the configuration, as demonstrated in the example below.

<Logging>
    <Target>
        <Protocol>file</Protocol>
        <Level>info</Level>
        <FileName>
            log/log-%Y-%m-%dT%H%M%S.log
        </FileName>
        <RotationThreshold>2G</RotationThreshold>
    </Target>
</Logging>

In the above example, a log file will be created in the $AMPSDIR/log named 2011-01-01-120000.log if the log was created at noon on January 1, 2011.

AMPS provides full support for the date tokens provided by the standard strftime function, with the exception of %n, as described above. The following table shows some of the most commonly used tokens:

Token
Description
Example

%a

Short weekday name

Fri

%A

Full weekday name

Friday

%b

Short month name

Feb

%B

Full month name

February

%c

Simple date and time

Fri Feb 14 17:25:00 2014

%C

Century

20

%d

Day of the month (leading zero if necessary)

05

%D

Short date format (MM/DD/YY)

02/20/14

%e

Day of the month (leading space if necessary)

5

%F

Short date format (YYYY-MM-DD)

2014-02-20

%H

Hour (00-23)

17

%I

Hour (00-12)

05

%j

Day of the year (001-366)

051

%m

Month (01-12)

02

%p

AM or PM

PM

%r

Current time, 12 hour format

05:25:00 pm

%R

Current time, 24 hour format

17:25

%T

ISO 8601 Time format

17:25:00

%u

ISO 8601 day of the week (1-7, Monday = 1)

5

%V

ISO 8601 week number (00-53)

07

%y

Year, last two digits

14

%Y

Year, four digits

2014

%Z

Timezone name or abbreviation (blank if undetermined)

PST

Using Units in the Configuration

To make configuration easy, AMPS permits the use of units to expand values. For example, if a time interval is measured in seconds, then the letter s can be appended to the value. For example, the following SOW topic definition uses the Expiration tag to set the record expiration to 86400 seconds (one day).

<SOW>
    <Topic>
        ...

        <Expiration>86400s</Expiration>

        ...
    </Topic>
</SOW>

An even easier way to specify an expiration of one day is to use the following Expiration:

<SOW>
    <Topic>
        ...

        <Expiration>1d</Expiration>

        ...
    </Topic>
</SOW>

The table below shows a listing of the time units AMPS supports in the configuration file.

Units

Description

ns

nanoseconds

us

microseconds

ms

milliseconds

s

seconds

m

minutes

h

hours

d

days

w

weeks

AMPS configuration supports a similar mechanism for byte-based units when specifying sizes in the configuration file. The table below shows a listing of the byte units AMPS supports in the configuration file.

Units

Description

kb

kilobytes

mb

megabytes

gb

gigabytes

tb

terabytes

Dealing with large numbers in AMPS configuration can also be simplified by using common exponent values to handle raw values. This means that instead of having to input 10000000 to represent ten million, a user can input 10M. The table below contains a list of the exponents supported.

Units

Description

k

10^3 - thousand

M

10^6 - million

To make it easier to remember the units, AMPS interval and byte units are not case sensitive.

Environment Variables in AMPS Configuration

AMPS configuration also allows for environment variables to be used as part of the data when specifying a configuration file. These variables can be set in the environment when AMPS starts or passed to AMPS using the -D option on the command line.

If a global system variable is commonly used in an organization, then it may be useful to define this in one location and re-use it across multiple AMPS installations or applications. AMPS will replace any token wrapped in ${} with the environment variable defined in the current user operating system environment. The example below demonstrates how the environment variable ENV_LOG is used to define an environment variable for the location of the host logging.

<Logging>
    <Target>
        <Protocol>file</Protocol>
        <FileName>${ENV_LOG}</FileName>
        <Level>info</Level>
        <RotationThreshold>2G</RotationThreshold>
    </Target>
</Logging>

Internal Environment Variables

In addition to supporting custom environment variables, AMPS includes a set of environment variables automatically populated by the server.

These variables are listed below:

Variable Name
Contains

AMPS_CONFIG_DIRECTORY

Directory in which the configuration file used to start AMPS is located.

AMPS_CONFIG_PATH

Full path to the configuration file used to start AMPS, including the file name.

AMPS_VERSION

Full version number of the AMPS server.

When AMPS processes the configuration file, AMPS expands these variables just as though they were set in the environment. For example, assume that AMPS was started with the following command at the command prompt:

%>./ampServer ../amps/config/config.xml

Given this command, the log file configuration option shown in the example below can be used to instruct AMPS to create the log files in the same parent directory as the configuration file — in this case ../amps/config/logs/infoLog.log.

<Logging>
    <Target>
        <Protocol>file</Protocol>
        <FileName>${AMPS_CONFIG_DIRECTORY}/logs/infoLog.log</FileName>
        <Level>info</Level>
        <RotationThreshold>2G</RotationThreshold>
    </Target>
</Logging>
PreviousGetting Started With AMPS ConfigurationNextWorking With Configuration Files

Last updated 1 year ago