Instance Level Configuration

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.

AMPS Process Options

Required Configuration

Element

Description

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.

Typical Options

Option	Description
Group	Identifies the replication group for this instance. If no Group element is present, the replication group for this instance is set to the Name of the instance. Set the group parameter when being able to refer to a set of instances that should be treated as identical for replication purposes makes replication configuration easier. Instances that have the same Group value should be intended to be exactly equivalent for the purposes of message contents and failover. If two instances are intended to be treated differently for the purposes of failover or replication, or are intended to have different contents, they should be given different Group names. Replication passthrough uses the group name to specify which instances to provide passthrough for. See the AMPS User Guide for a discussion of replication, including passthrough. When the Group is not set explicitly, the Group defaults to the instance Name.
ProcessName	Specifies the process name to set for this instance. When this element is present, AMPS uses the name specified as the process name. Otherwise, the process name uses the default set by Linux, which is the executable name (ampServer or ampServer-compat unless the executable has been renamed.) This element is most useful for systems that host multiple AMPS instances and want to be able to quickly tell the instances apart based on the process name. This element is optional. If not present, the AMPS executable does not change the process name.
Description	This element is used to provide a description of the AMPS instance for monitoring tools (including the AMPS Galvanometer). AMPS provides the contents of this element in the admin interface, but does not use the description for any other purpose.
Environment	This element is used to provide information about the environment of the AMPS instance to monitoring tools (including the AMPS Galvanometer). AMPS provides the contents of this element in the admin interface, but does not use this element for any other purpose.

Config Management

Option	Description
SuggestedMinimumVersion	The suggested minimum AMPS version to use this configuration file. If the AMPS instance that loads this configuration file has a version number less than the suggested minimum version, AMPS issues a warning. This option can be useful when upgrading a set of AMPS instances, or when the AMPS instance will see improved performance from a particular feature. For example, an application that will run correctly without hash indexes, but would see improved performance with hash indexes, could provide a SuggestedMinimumVersion of 4.3.1.0. Default: When no value is provided, AMPS does not check the configuration file against the version number of the instance.
RequiredMinimumVersion	The required minimum AMPS version to use this configuration file. If the AMPS instance that loads this configuration file has a version number less than the suggested minimum version, AMPS issues an error and will not start. This option can be useful for enforcing upgrade on a set of AMPS instances, or when the AMPS instance must support a particular feature. For example, an application that uses message queues could provide a RequiredMinimumVersion of 5.0. Default: When no value is provided, AMPS does not check the configuration file against the version number of the instance.
ConfigIncludeCommentDefault	Sets the default for how Include directives indicate the source of the content. When this option is set to true or enabled, content inserted through an Include directive is surrounded by comments indicating the source of the content. Default: false, which specifies that AMPS will not surround included content with comments.
ConfigCycleDetectionThreshold	Sets the maximum size to allow for an expanded configuration file. This setting is intended to prevent cycles of include files (for example, where file A includes file B and file B includes file A) from consuming all of the memory on the system before failing. Default: 5MB

<AMPSConfig>
    ....

    <Name>AMPS</Name>
    <Group>Sample-AMPS</Group>

    ....
   
</AMPSConfig>

Authentication and Entitlements Management

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 Authentication section for the details on setting identity management for the instance. See the Entitlement section for details on setting permissions for the instance.

Slow Client Policies

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.

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 User Guide.

Instance-Wide Options

This table describes policies that are applied based on the total resource consumption of clients.

Option	Description
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

Per-Client Options

This table describes the slow client policies that are applied based on the behavior of an individual client.

Option	Description
ClientMessageAgeLimit	The maximum amount of time for the client to lag behind. If the oldest message buffered in AMPS for a client has been held longer than this time, that client will be disconnected. This parameter is an AMPS time interval (for example, 30s for 30 seconds, or 1h for 1 hour). Default: No age limit
ClientMaxCapacity	The amount of available capacity a single client can consume. Before a client is offlined, this limit applies to the MessageMemoryLimit. After a client is offlined, this limit includes the MessageDiskLimit. This parameter is a percentage of the total limit available to the instance. This limit is set as a percentage of the total amount of capacity available. Default: 50% in this version of AMPS. Note that versions of AMPS previous to 5.3.4 default to 100%

Minidump Settings

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 AMPS Monitoring Guide).

AMPS allows you to set the directory in which minidump files will be created and the permissions mask for minidump files.

Option	Description
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

<AMPSConfig>
    ...

    <MiniDumpDirectory>/var/tmp</MiniDumpDirectory>
    <MiniDumpFileMask>0644</MiniDumpFileMask>

    ...
</AMPSConfig>

Tuning

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.

Option	Description
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.

<AMPSConfig>
    ....
    <Tuning>
        <NUMA>
            <Enabled>enabled</Enabled>
        </NUMA>
    </Tuning>
    ....
</AMPSConfig>

Externals

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.

Option	Description
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

<AMPSConfig>
    <Externals>
        <SSL>
            <Library>/opt/audited/libopenssl.so</Library>
        </SSL>
        <Crypto>
            <Library>/opt/audited/libcrypto.so</Library>
        </Crypto>
        <Curl>
            <Library>/opt/resolver/lib/libcurl.so</Library>
        </Curl>
    </Externals>
</AMPSConfig>

Specialized Options

This section describes options that are configured at the instance level for specialized purposes.

Option	Description
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.