3. Instance Level Configuration

This chapter describes elements of the AMPS configuration that set parameters for the instance as a whole.

Element	Description
Name	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, and is shown in log statements and 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.
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 have identical message contents. If two instances 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. 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.
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. Defaults to true.
Authentication	Sets the default authentication module to use for transports that do not verify the identity of a connected user. The module specified must be one of the modules configured in the Modules element or one of the authentication modules that AMPS loads by default. See Table 12.2 for the list of default modules. Defaults to amps-default-authentication-module.
Entitlement	Sets the default entitlement module to use for transports that do not explicitly specify an entitlement module. Entitlement modules enforce permissions for a connected user. The module specified must be one of the modules configured in the Modules element or one of the modules that AMPS loads by default. See Table 13.2 for the list of default modules. Defaults to: amps-default-entitlement-module
Authenticator	Sets the default authenticator module to use for outgoing connections from AMPS that do not explicitly specify an authenticator module. Authenticator modules provide credentials to use for outgoing connections. The module specified must be one of the modules configured in the Modules element or one of the modules that AMPS loads by default. Defaults to: amps-default-authenticator-module
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. Defaults: 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. Defaults: 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. Defaults: Defaults to 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. Defaults: Defaults to 5MB.

Table 3.1: Instance Level Configuration Parameters

<AMPSConfig>
    ....

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

    ....
</AMPSConfig>

Example 3.1: Instance-Level Configuration Example

SOW Statistics Interval

AMPS can publish SOW statistics for each SOW topic which has been configured. The SOWStatsInterval is specified as an interval (see Table 3.2) between updates to the /AMPS/SOWStats topic.

Element	Description
SOWStatsInterval	Interval for which SOW statistics are updated.

Table 3.2: SOW Statistics Interval Parameters

<AMPSConfig>
    ...

    <SOWStatsInterval>10s</SOWStatsInterval>

    ...
</AMPSConfig>

Example 3.2: Sow Statistics Interval Example

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.

Element	Description
MessageMemoryLimit	The total amount of memory to allocate to messages before offlining clients. This 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. Default: 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 value would default to 25GB. This option is specified in bytes, and accepts the standard AMPS notation (for example, 10GB or 250MB).
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
ClientMessageAgeLimit	The maximum amount of time for the client to lag behind. If a message for the client has been held longer than this time, the 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. Default: 100% (no effective limit)

Table 3.3: Slow Client Management

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 Reference Guide).

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

Element	Description
MiniDumpDirectory	Location to store AMPS mini dumps. Default is /tmp. If the directory does not exist, AMPS creates the directory. The special value disabled configures AMPS not to produce mini dumps.
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 umask command, and AMPS applies this mask exactly as the umask command would. The file is created with the user and group that the AMPS server process runs under. AMPS accepts a maximum value of 666 for the mask. For example, here are some common umask settings: Value Result 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.

Table 3.4: Mini Dump Directory Parameters

<AMPSConfig>
    ...

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

    ...
</AMPSConfig>

Example 3.3: MiniDump Configuration Example

Configuration Validation

The configuration validation option can be used to enable or disable the validation checking performed by AMPS on the initialization of each instance. Disabling the configuration validation can cause AMPS to start in an invalid state or not properly log warnings or errors in the configuration file.

Caution

Configuration validation should only be disabled during testing or debugging in cases where it is known that the configuration may produce errors (for example, while developing a configuration generator). 60East strongly recommends against disabling configuration validation in a production or development environment.

Element	Description
ConfigValidation	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.

Table 3.5: Config Validation Parameters

<AMPSConfig>
    <ConfigValidation>enabled</ConfigValidation>
</AMPSConfig>

Example 3.4: Configuration Validation Example

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.

Caution

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.

Element

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

Table 3.6: Tuning Parameters

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

Example 3.5: Tuning Example

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.

Element	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.0.2 or later. 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. 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

Table 3.7: Externals Parameters

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

Example 3.6: Externals Example