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

Element Description

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.

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.

Option Description

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.

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.

Option Description

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

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.

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

Option Description

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`

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

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

Option Description

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

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

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

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

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

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

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

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

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`

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

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.

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.

PreviousIncluding External Files NextAdmin Server and Statistics

Last updated 7 days ago