Instance Level Configuration
Last updated
AMPS Server Documentation 5.3.4
Last updated
This chapter describes elements of the AMPS configuration that set parameters for the instance as a whole.
The tabs below describe the options available at the instance level of the AMPS configuration file.
Name
(required)
This element defines the name of your AMPS instance. The instance name is used to uniquely identify this instance for replication purposes, to generate file names for use by the AMPS instance, that is shown in log statements and used for other administrative purposes.
60East recommends that the name be short and meaningful, and that each instance in your AMPS installation have a distinct name. When creating a name, the name should not contain special characters such as spaces, path separator characters (/ or \), or characters that will be interpreted by the Linux shell ($ or ~).
60East recommends that the name of the instance stay the same for as long as the application will be connected to the same replication partners or retain transaction log data. This name is used in the files created by the instance as part of the transaction log, in the replication path for replicated instances, and in the client names created for replication connections. If your AMPS installation will use replication, the Name of each instance must be unique within the set of replicated instances.
This element is required, and there is no default.
AMPS authentication and entitlements are managed for each Transport. You can set the default to use for all transports at the instance level.
See the section for the details on setting identity management for the instance. See the section for details on setting permissions for the instance.
AMPS includes a set of parameters that specify how the instance should manage slow clients. Sometimes, AMPS can publish messages faster than an individual client can consume messages, particularly in applications where the pattern of messages includes "bursts" of messages. Clients that are unable to consume messages faster or equal to the rate messages are being sent to them are ”slow clients”. By default, AMPS queues messages for a slow client in memory to grant the slow client the opportunity to catch up. However, scenarios may arise where a client can be over-subscribed to the point that the client cannot consume messages as fast as messages are being sent to it. In particular, this can happen with the results of a large SOW query, where AMPS generates all of the messages for the query much faster than the network can transmit the messages.
This table describes policies that are applied based on the total resource consumption of clients.
MessageMemoryLimit
The total amount of memory to allocate to messages before offlining messages (that is, beginning to buffer messages to disk).
This value applies to all clients. For example, setting a value of 500MB means that all clients that this limit applies to will share 500MB for all buffered messages to those clients.
This option is specified in bytes, and accepts the standard AMPS notation (for example, 10GB or 250MB).
Default: The default value is calculated when AMPS starts as 10% of total host memory or 10% of the amount of host memory AMPS is allowed to consume (as reported by ulimit -m ), whichever is lowest.
For example, if a host has 250GB of memory, and ulimit -m for the AMPS process is unlimited, the default value for AMPS when started on that system is 25GB.
MessageDiskLimit
The total amount of disk space to allocate to messages before disconnecting clients.
Default: 1GB or the amount specified in the MessageMemoryLimit, whichever is highest.
This option is specified in bytes, and accepts the standard AMPS notation (for example, 10GB or 250MB)
MessageDiskPath
The path to use to write offline files.
Default: /var/tmp
AMPS allows you to set the directory in which minidump files will be created and the permissions mask for minidump files.
MiniDumpDirectory
Location to store AMPS minidump files. Default is /tmp. If the directory does not exist, AMPS creates the directory.
The special value disabled configures AMPS not to produce minidumps.
MiniDumpFileMask
Permissions mask for minidump files.
The value of the mask is an octal number (by convention, four digits) in the same format as the standard chmod command, and AMPS applies this mask exactly as the chmod command would. This is the mask AMPS will apply to the file after it's created. The file is created with the user and group that the AMPS server process runs under.
0444 File is readable by owner, group, and any user.
0440 File is readable by owner and members of the owner's group
0400 File is readable by owner only
0664 File is readable and writable by owner and members of the owner's group. File is readable by any user.
0644 File is readable and writable by owner. File is readable by members of the owner's group and any user.
Default: 0640, which makes the file readable and writable by the file owner and readable by members of the owner's group
The Tuning section of the configuration file sets instance-level parameters for tuning the performance of AMPS. In many cases, AMPS self-tunes to take advantage of the hardware and environment. However, explicitly setting tuning parameters is sometimes necessary in cases where an AMPS instance cannot determine the best value. For example, if multiple AMPS servers are running on the same system, 60East recommends disabling NUMA.
Use the Tuning element with care. Options in the Tuning element can affect AMPS performance, and the behavior of Tuning options may be version-specific.
NUMA/Enabled
Setting this to disabled will turn off AMPS NUMA tuning. The default is enabled, which affinitizes certain AMPS threads to specific processors.
The default value of enabled produces significantly better performance when a single instance of AMPS is running on a given system. However, if multiple instances of AMPS are running on the same system, setting this value to disabled for all of the instances on the system can reduce contention among the instances and produce better overall performance.
Likewise, if the system that hosts AMPS runs other CPU-intensive processes, setting this option to disabled can improve overall performance.
This option can also be set by setting the AMPS_NUMA environment variable.
Default: enabled
Replication/MinSyncDestinations
Setting this to a value will limit the number of replication destinations that AMPS will allow an action to downgraded to use async acknowledgement. When set, AMPS actions will not downgrade a destination if doing so would cause the number of destinations using sync acknowledgement to be less than the number set in this value. Notice that this value will not cause AMPS to upgrade a destination if a sync destination disconnects. This parameter affects only whether AMPS will downgrade a destination.
When no value is set, AMPS actions will downgrade any destination that meets the criteria in the downgrade action. Default: Unset
Queue/QueueDeliveryFlushInterval
This sets the maximum interval for a message queue delivery thread to wait to send messages to a client.
The default value typically gives a good balance between latency and throughput.
Decreasing this value may decrease the latency of message delivery from a queue at the expense of lower overall throughput.
Default: 250us
Minimum: 1us
TransactionLog/Indexing
Setting this to a value of topic will direct AMPS to create topic index for the transaction log. A topic index can reduce latency when replaying messages when multiple topics are recorded in the transaction log.
Enabling this is most useful when the transaction log records a large number of topics and replay latency is crucial for meeting the performance requirements of the application. In particular, this can improve replay if publishes to a given topic are separated by publishes to many other topics.
When this element is present, the contents of the element should be topic.
Default: Unset. By default, AMPS does not create topic indexes for the transaction log.
The AMPS server depends on external libraries for some functionality. The Externals configuration item allows you to control the exact shared object loaded for some of these external libraries, particularly those related to security.
SSL/Library
The path and shared object name of the SSL library to use for this instance. AMPS requires an SSL library that is compatible with OpenSSL 1.1. By default, AMPS specifies the object name, and uses the standard shared object loading mechanism to resolve the object name. With this configuration option, you can direct AMPS to load a specific shared object.
Default: libopenssl.so
Crypto/Library
The path and shared object name of the cryptography library to use for this instance. By default, AMPS specifies the object name, and uses the standard shared object loading mechanism to resolve the object name. With this configuration option, you can direct AMPS to load a specific shared object.
Default: libcrypto.so
Curl/Library
The path and shared object name of the libcurl shared object. By default, AMPS specifies the object name and loads the version of libcurl included with the AMPS distribution as necessary. With this configuration item, you can direct AMPS to load a specific shared object.
Default: libcurl.so
This section describes options that are configured at the instance level for specialized purposes.
SOWStatisticsInterval
AMPS can publish SOW statistics for each SOW topic which has been configured. The SOWStatisticsInterval is specified as an interval between updates to the /AMPS/SOWStats topic.
Set this option if an application will subscribe to the /AMPS/SOWStats topic or that topic is included in the State of the World.
RegexTopicSupport
Sets whether this instance supports regular expression topic matching.
When this option is true, clients can register subscriptions using regular expressions and receive messages for all matching topics. When this option is false, regular expression characters are interpreted as literal characters. Likewise, when this option is true, Topic specifications in replication configuration, transaction log configuration, and so on can use regular expressions.
60East recommends leaving this option set to the default unless there is a specific reason to change it, and unless the configuration and applications have been reviewed to ensure no regular expression topics are used.
Default: true
ConfigValidation
Sets whether AMPS validates the configuration file when starting.
Setting this to disabled will turn off AMPS configuration validation. The default is enabled, ensuring that the current AMPS configuration meets valid parameter ranges and data types.
When this option is set to disabled, AMPS may start with an inconsistent or invalid configuration, which may have unpredictable effects, including data loss or AMPS unexpectedly exiting.
This option is included in cases where it may be necessary to start with a file that is known to be invalid, such as when testing applications that generate configuration files.
Replication passthrough uses the group name to specify which instances to provide passthrough for. See the for a discussion of replication, including passthrough.
Slow client management is one of the ways that AMPS prevents slow clients from disrupting service to the instance. 60East recommends enabling slow client management for instances that serve high message volume or are mission critical. Slow client policies for all Transports in the instance are set at the root level of the configuration file. A Transport can override any of these settings, or choose to use the instance-wide settings. Details on slow client handling are available in the .
AMPS minidumps contain information on the current state of the AMPS program execution, which is useful for support and diagnostics. AMPS will generate a minidump file on any crash event, or a minidump file can be generated at any point in time through the monitoring interface (see the ).