Guide for Persistence
|
The operating parameters for umestored come from an XML configuration file that must be supplied on the command line (see Man Pages for Store. Umestored contains a UM context and receivers that may be configured with default values through a UM configuration file referenced in the XML configuration file. Default UM options my be overridden for each configured store using the XML configuration file.
You configure umestored to instantiate stores with the umestored XML configuration file, which Ultra Messaging reads at start up.
The umestored XML configuration file for persistence has the following sections.
Daemon section - holds administrative parameters for such things as the location of log files, the UM Configuration File, etc.
High Level Store Configuration File:
Container element that holds the configuration for the Persistent Store process. Also defines the version of the configuration format used by the file.
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
version | Version number of UME store XML DTD that the configuration file corresponds to. See umestored Configuration DTD for a description of the different versions. Users are encouraged to update their Store configuration files to correspond to the latest version supported by the Store software in use. | string | (no default; must be specified) |
Example:
Container element for one or more <store> elements. A store process can run multiple independent store instances. Some users prefer to run multiple store instances in a single process to reduce their process management complexity. Other users prefer to run multiple store processes, each with a single store instance, to reduce the impact of a store process failing.
There should be little or no performance difference between multiple store instances running in the same process vs. multiple store processes on the same host. However, for maximum store performance, it is generally easier to pin store threads to cores when each process is running a single store instance.
It is NOT recommended for multiple stores within a Q/C group to run in the same process, or even the same host, as this defeats the goal of reliability through redundancy.
Example:
Configuration for a Store instance.
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
name | Identifies log messages for this store instance in the umestored log file. | attr_name | (no default; must be specified) |
interface | Specifies the IP address over which umestored accepts connection requests for this store. You can specify a single IP address, such as 10.29.3.16, or a range of addresses, 10.29.3.16/25. See also Identifying Persistent Stores. | string | "0.0.0.0" (INADDR_ANY) |
port | TCP port where umestored should listen for connection requests to this store. | string | (no default; must be specified) |
Example:
Container for <topic> elements. Defines the topics that this store instance will persist.
Example:
Defines a topic pattern which the Store will use to find sources to persist. Also contains configuration information about those topics.
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
pattern | A string that is used to discover sources to be persisted. The string can be a simple topic name (type="direct" ), or it can be a regular expression (type="pcre" ) which can match more than one topic. | string | (no default; must be specified) |
type | How the pattern attribute should be interpreted. | "direct" - Topic name (exact string match) "PCRE" - Perl regular expression. "regexp" - Posix regular expression. Deprecated; do not use. | direct |
Example:
In this example, the topic "NYSE.xyz" and all topics that start with "alert." are persisted in the "MyStore1" store instance.
Container for a set of <option> elements.
Example:
In this example, some options are at the "store" level and apply to all topics. Other options are specific to the topic "NYSE.xyz".
Set a configuration option of a particular type. See Options for a Store's ume-attributes Element for more information on the available options.
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
type | Type of configuration option. | "lbm-receiver" - UM configuration option of scope "receiver". "lbm-context" - UM configuration option of scope "context". "lbm-source" - UM configuration option of scope "source". "store" - Store configuration option. | (no default; must be specified) |
name | Name of option. | attr_name | (no default; must be specified) |
value | Value for option. | string | (no default; must be specified) |
Example:
In this example, some options are at the "store" level and apply to all topics. Other options are specific to the topic "NYSE.xyz".
Set how often the store publishes its daemon stats. See Daemon Statistics for general information on Daemon Statistics.
Example:
Daemon Statistics are configured at both the daemon level and at the store level.
Configures the rate at which one particular grouping of Daemon Statistics messages are published. See Daemon Statistics for general information on Daemon Statistics.
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
name | Name of statistics group being configured. | "default" - Sets a default interval for all message types. "store" - Sets the interval for messages of type umestore_store_dmon_stat_msg_t. "source" - Sets the interval for messages of type umestore_repo_dmon_stat_msg_t. "receiver" - Sets the interval for messages of type umestore_rcv_dmon_stat_msg_t. "disk" - Sets the interval for messages of type umestore_disk_dmon_stat_msg_t. "config" - Sets the interval for messages of types umestore_*_dmon_config_msg_t. "memory" - Sets the interval for messages of type umestore_smart_heap_dmon_stat_msg_t. | (no default; must be specified) |
ivl | Time, in seconds, between publishing the statistics group being configured. | string | (no default; must be specified) |
Example:
Daemon Statistics are configured at both the daemon level and at the store level.
Container element for configuration elements that apply to the entire Store process.
Example:
The daemon-monitor element configures the store daemon for Daemon Statistics.
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
topic | Topic name for used to publish daemon statistics. | string | "umestore.monitor" |
Example:
Daemon Statistics are configured at both the daemon level and at the store level.
Controls if the daemon will respond to requests from monitoring applications. See Daemon Statistics Requests.
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
allow | Enables handling requests. | "0" - Disable request handling. "1" - Enable request handling. | "0" |
Example:
Daemon Statistics are configured at both the daemon level and at the store level.
Controls if the daemon will respond to requests from monitoring applications. See Daemon Statistics Requests.
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
allow | Enables handling requests. | "0" - Disable request handling. "1" - Enable request handling. | "0" |
Example:
Daemon Statistics are configured at both the daemon level and at the store level.
Pathname for UM configuration file which is used to configure UM for either the store or for daemon statistics, depending on the parent element.
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
xml:space | Specifies how whitespace (tabs, spaces, linefeeds) are handled in the element content. | "default" - Trim leading and trailing whitespace, and compress multiple whitespace characters into a single space. "preserve" - Retain whitespace exactly as entered. | default |
Example:
Address and port for the Store web-based monitor. Format is "Address:Port", where "Address" is either an IP address of one of the host's interfaces, or is "*" which allows the use of any interface. See Store Web Monitor for more information.
If omitted, the web monitor is disabled.
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
xml:space | Specifies how whitespace (tabs, spaces, linefeeds) are handled in the element content. | "default" - Trim leading and trailing whitespace, and compress multiple whitespace characters into a single space. "preserve" - Retain whitespace exactly as entered. | default |
Example:
Pathname for UM license file. NOTE: a license key is no longer required for Store operation. This element is retained for backwards compatibility.
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
xml:space | Specifies how whitespace (tabs, spaces, linefeeds) are handled in the element content. | "default" - Trim leading and trailing whitespace, and compress multiple whitespace characters into a single space. "preserve" - Retain whitespace exactly as entered. | default |
Pathname for UM XML configuration file. See also UMP Element "<lbm-config>".
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
xml:space | Specifies how whitespace (tabs, spaces, linefeeds) are handled in the element content. | "default" - Trim leading and trailing whitespace, and compress multiple whitespace characters into a single space. "preserve" - Retain whitespace exactly as entered. | default |
application-name | Specifies the "application name" of the store process, for use within the UM XML configuration file. See XML Application Names for more information on application names. | string | "umestored" |
Example:
Specifies a Group ID (GID) for daemon process (if run as root).
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
xml:space | Specifies how whitespace (tabs, spaces, linefeeds) are handled in the element content. | "default" - Trim leading and trailing whitespace, and compress multiple whitespace characters into a single space. "preserve" - Retain whitespace exactly as entered. | default |
Example:
Contains the pathname for daemon process ID (PID) file.
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
xml:space | Specifies how whitespace (tabs, spaces, linefeeds) are handled in the element content. | "default" - Trim leading and trailing whitespace, and compress multiple whitespace characters into a single space. "preserve" - Retain whitespace exactly as entered. | default |
Example:
Specifies a User ID (UID) for daemon process (if run as root).
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
xml:space | Specifies how whitespace (tabs, spaces, linefeeds) are handled in the element content. | "default" - Trim leading and trailing whitespace, and compress multiple whitespace characters into a single space. "preserve" - Retain whitespace exactly as entered. | default |
Example:
Contains the path name of the store log file. See Store Rolling Logs for more information.
If omitted, log messages are written to standard output.
XML Attributes:
Attribute | Description | Valid Values | Default Value |
---|---|---|---|
type | Where to write log messages. | "file" - Write log messages to a file. "console" - Write log messages to standard output. | "console" |
frequency | Time-frame by which to roll the log file. | "disable" - Do not roll the log file based on time. "daily" - Roll the log file at midnight. "hourly" - Roll log file after approximately an hour, but is not exact and can drift significantly over a period of time. "test" - For internal Informatica use only. Do not use. | "disable" |
size | Size (in MB, i.e. 2**20, or 1,048,576) of current log file at which it is rolled. Specify 0 to disable rolling by log file size. | string | "10" |
xml:space | Specifies how whitespace (tabs, spaces, linefeeds) are handled in the element content. | "default" - Trim leading and trailing whitespace, and compress multiple whitespace characters into a single space. "preserve" - Retain whitespace exactly as entered. | default |
Example:
Inside a '<ume-attributes>
' section, options are set with one or more '<option ...>
' elements. Each '<option ...>
' element contains a 'type'
attribute, a 'name
' attribute, and a 'value
' attribute. The 'type
' attribute identifies the scope of the option (context, receiver, source, or store), the 'name
' attribute identifies the individual option being set, and the 'value
' attribute supplies the value.
Options with a type of "lbm-source", "lbm-receiver", or "lbm-context" are UM configuration options, which the store passes to the UM library.
For example, the option element:
<option type="lbm-context" name="transport_lbtrm_receiver_socket_buffer" value="1048576"/>
sets the UM configuration option transport_lbtrm_receiver_socket_buffer (context) (receiver socket buffer size for LBT-RM) to 1 megabyte.
See the UM Configuration Guide for the full list of UM configuration options.
Store options without a type attribute or those explicitly given a type attribute of 'store
' simply configure the store itself.
For example, the option element:
<option type="store" name="disk-cache-directory" value="cache"/>
sets the store's disk cache directory.
The following table gives options allowed for a store element. Use the 'store
' option type for these options.
Option | Description | Default Value |
disk-cache-directory | Pathname for disk store message cache directory. Must be between 1 and 230 characters long. | umestored-cache |
disk-state-directory | Pathname for disk store state directory. Must be between 1 and 230 characters long. | umestored-state |
allow-proxy-source | Allows the store to act as a proxy source in case a registered source terminates. | 0 (Disable) |
context-name | Name of the store that can be used by sources to refer to the store instead of the address:port. Restricted to 128 characters in length, and may contain only alphanumeric characters, hyphens, and underscores. A store runs in its own context, so the store's context name can be used to identify the store. UM automatically resolves store names, which can facilitate persistent operation across the UM Router. A context name must be unique across the entire network and not be the same as any context names used in a UMM XML configuration. See also Identifying Persistent Stores | None. |
retransmission-request-processing-rate | Specifies the number of retransmission requests processed by a store per second across all topics. The store drops all retransmission requests that exceed this value. | 262144 |
As with Options for a Store's ume-attributes Element, options for a topic's ume-attributes element can set both UM configuration options as well as store configuration.
The following table gives options allowed for a topic element. Use the store Option Type for these options.
Option | Description | Default Value |
---|---|---|
retransmission-request-forwarding | If enabled (value = 1), the store forwards retransmission requests to sources if and only if the store does not have the data. If disabled (value = 0), the store services retransmission requests for data it has, and does not forward requests to sources for data it does not have. | 0 (store services retransmission requests and does not forward requests) |
repository-type | Specifies how messages should be retained by the store. Possible values:
|
|
repository-size-threshold | For topics with a repository-type of memory, disk or reduced-fd, specifies the minimum number of message bytes (includes payload, headers, and store structure overhead) retained for a topic before the repository starts to delete old messages. Pertains to a memory store or the memory cache of a disk or reduced-fd repository. For RPP repositories, this value only includes message payload. Also for RPP, the source may optionally override this value with a value less than or equal with the source configuration option ume_repository_size_threshold (source). (units: bytes) | 25165824 (24 MB) |
repository-size-limit | For topics with a repository-type of memory, disk or reduced-fd, specifies the maximum number of message bytes (includes payload, headers, and store structure overhead) retained for each source. Pertains to a memory store or the memory cache of a disk or reduced-fd repository. For RPP repositories, this value only includes message payload. Also for RPP, the source may optionally override this value with a value less than or equal with the source configuration option ume_repository_size_limit (source) (units: bytes) | 50331648 (48 MB) |
repository-age-threshold | For topics with a repository-type of memory, disk or reduced-fd, specifies how long the repository keeps a message available. Pertains to a memory store or the memory cache of a disk or reduced-fd repository. The repository reclaims space used to store messages that exceed this threshold. A value of 0 means message age is not considered in retention decisions. (units: seconds) | 0 |
repository-disk-max-async-cbs | For topics with a repository-type of disk or reduced-fd, specifies the maximum number of outstanding async I/O callbacks for reading and writing messages to disk. (units: async callbacks) | 16 callbacks |
repository-disk-max-write-async-cbs | For topics with a repository-type of disk or reduced-fd, specifies the maximum number of outstanding async I/O callbacks for writing messages to disk. Reducing this option can improve throughput by batching more fragments into a single write. (units: async callbacks) This option is deprecated. | 16 callbacks |
repository-disk-max-read-async-cbs | For topics with a repository-type of disk or reduced-fd, specifies the maximum number of outstanding async I/O callbacks for reading messages from disk. Raising this value can improve recovery rates. For topics with a repository-type of reduced-fd, Informatica recommends a value of 200 times the number of expected receivers per topic. (units: async callbacks) | 16 callbacks |
repository-disk-file-size-limit | For topics with a repository-type of disk or reduced-fd, specifies the maximum amount of disk space that will be used to store retained messages. A minimum value of 196992 is enforced. For RPP, the source may optionally override this value with a value less than or equal with the source configuration option ume_repository_disk_file_size_limit (source). (units: bytes) | 104857600 (100 MB) |
repository-disk-file-preallocate | For topics with a repository-type of disk, if set to 1, UM pre-allocates a store's cache files to match their maximum size on disk (as configured by repository-disk-file-size-limit) upon creation, as opposed to growing to that size as the store receives new messages. For ext3/4 and NTFS file systems, this options creates a sparse file, which does not allocate all of the underlying data blocks. Advantages of pre-allocation include better performance on rotating disks due to less file fragmentation, and knowing that enough disk space exists for any new source that registers. Disadvantage is the time to create the cache files, especially if many sources register at once. | 0 (zero) - do not pre-allocate |
repository-disk-async-buffer-length | For topics with a repository-type of disk or reduced-fd, specifies the size of the buffers that will be used in async I/O operations for reading and writing messages to disk. A minimum value of 65664 is enforced. (units: bytes) | 1024000 |
repository-disk-message-checksum | For topics with a repository-type of disk or reduced-fd, specifies whether the messages saved to disk should include a checksum field or not for validation if the store is restarted. (units: flag) | 0 (disabled) |
source-activity-timeout | Establishes the period of time from a source's last activity to the release of the source's RegID. Stores return an error to any new source requesting the source's RegID during this period. If proxy sources are enabled (ume_proxy_source (source)) the store does not release the source's RegID and UM elects a proxy source. If neither proxy sources nor ume_state_lifetime (source) are configured, the store also deletes the source's state and cache. Can be overridden by ume_activity_timeout (source). See also Persistence Proxy Sources. (units: milliseconds) | 30000 (30 seconds) |
source-state-lifetime | Establishes the period of time from a source's last activity to the deletion of the source's state and cache by the store, regardless of whether a proxy source has been created or not. You can also configure ume_state_lifetime (source) for the source. The store uses whichever is shorter. See also Persistence Proxy Sources. (units: milliseconds) | 0 (zero) |
receiver-activity-timeout | Establishes the period of time from a receiver's last activity to the release of the receiver's RegID. Stores return an error to any new request for the receiver's RegID during this period. Can be overridden by ume_activity_timeout (source). See also Persistence Proxy Sources. (units: milliseconds) | 30000 (30 seconds) |
receiver-state-lifetime | Establishes the period of time from a receiver's last activity to the deletion of the receiver's state and cache by the store. You can also configure ume_state_lifetime (receiver) for the receiver. The store uses whichever is shorter. See also Persistence Proxy Sources. (units: milliseconds) | 0 (zero) |
source-check-interval | Specifies how often a store will check for activity of sources and receivers. (units: milliseconds) | 750 (750 milliseconds) |
keepalive-interval | Specifies how often a store will generate keepalive traffic to sources and receivers if there has been no traffic required in the normal course of operation. (units: milliseconds) | 3000 (3 seconds) |
receiver-new-registration-rollback | Specifies the number of stabilized messages that a newly registered receiver should consume. For example, setting this to 10 "rolls back" the new receiver's starting message to the 10th most recent message. This value must be positive and less than 2147483648. The recommended value of 2147483647 indicates that the rollback should begin at the start of the stream. A value of 0 indicates the store should instruct the receivers to start with the next new message from the source known by the store. (units: messages) | 2147483647 (rollback starts at beginning of stream) |
proxy-election-interval | Specifies the interval, in milliseconds, used when electing a proxy source. When a source, which requested that a proxy source be provided for it, has been detected as no longer active, each store eligible to provide a proxy source for it waits for an amount of time which is randomized in the range [0.5*proxy-election-interval .. 1.5*proxy-election-interval]. If no other store has been elected to serve as the proxy source, the store declares itself as the proxy source. (units: milliseconds) | 60,000 (60 seconds) |
stability-ack-interval | Specifies the maximum amount of time that stability acknowledgments will be batched before being sent to a source. Batching stability ACKs can increase throughput of stores (especially memory stores) significantly, but introduces a delay between when a message is actually stable in the store and when the source is notified of message stability. (units: milliseconds) | 200 (200 milliseconds) |
stability-ack-minimum-number | Specifies the minimum number of message stability acknowledgments that must accumulate before a stability ACK is sent to a source. With the default value of 1, stability ACKs are sent immediately as soon as messages are stable. Increasing this value causes stability ACKs to be batched, which can increase throughput of stores (especially memory stores) significantly, but introduces a delay between when a message is actually stable in the store and when the source is notified of message stability. If using a stability ACK-based flight size on a persistent source in combination with this option, it is advisable to make sure stability-ack-minimum-number is set less than or equal to the source's flight size. Otherwise, stability ACKs will only be sent upon expiration of the stability-ack-interval timer, resulting in bursty stop-and-go sending. (units: number of message fragments) | 1 (1 fragment) |
repository-allow-receiver-paced-persistence | Specifies if the repository allows receiver-paced persistence (1). If allowed, the source may optionally request RPP with ume_receiver_paced_persistence (source). Both must be done for RPP to be in effect. | 0 (store does not allow the source to specify RPP) |
repository-allow-ack-on-reception | For RPP, specifies if the repository allows the repository to perform "ack on reception" (1). If allowed, the source may optionally request "ack on reception" with ume_repository_ack_on_reception (source). Both must be done for "ack on reception" to be in effect. For SPP and memory stores, this option has no effect. See RPP Normal Operation for more information. | 0 (store does not allow the source to specify ack-on-reception behavior) |
repository-disk-write-delay | For topics with a repository-type of disk or reduced-fd, specifies the maximum delay in milliseconds after message reception before the repository persists a message to disk. For RPP, the source may optionally override this value with a value less than or equal with the source configuration option ume_write_delay (source). (units: milliseconds) | 0 milliseconds |
source-flight-size-bytes-maximum | With RPP, specifies the maximum number of in-flight payload bytes that the source is allowed to configure with ume_flight_size_bytes (source). If the source attempts to configure ume_flight_size_bytes (source) greater than the store's source-flight-size-bytes-maximum, the source registration is rejected. For SPP stores, this option has no effect (i.e. the source is not restricted in its configuration). See Persistence Flight Size for more information. (units: bytes) | 4194304 bytes (4MB) |
As mentioned in Options for a Store's ume-attributes Element, all options configured for '<ume-attributes>
' require an '<option>
' type, which specifies the scope of the option.
For example, here is a store configuration which illustrates several options being set of varying types:
The following table describes the Option Types:
Option Type | Description | Default Value |
---|---|---|
lbm-receiver | Allows you to configure receiver-scope options that you usually specify in an Ultra Messaging configuration file or set using lbm_*_attr_setopt(). For example, you could turn off delivery of NAKs for a particular topic by including the following within the topic's '<ume-attributes> ' element: <option type="lbm-receiver" name="transport_lbtrm_send_naks" value="0"/> ' <option> ' is a child of '<ume-attributes>' , but you can use option type lbm-receiver within only a '<topic> ' element, not a '<store> ' element. | None - this is a required attribute. |
lbm-context | Allows you to configure context-scope options that you usually specify in an Ultra Messaging configuration file or set using lbm_*_attr_setopt(). For example, you could increase the receiver socket buffer by including the following within the '<ume-attributes> ' element: <option type="lbm-context" name="transport_lbtrm_receiver_socket_buffer" value="1048576"/> ' <option> ' is a child of '<ume-attributes> ', but you can use option type lbm-receiver within only a '<store> ' element, not a '<topic> ' element. | None - this is a required attribute. |
lbm-source | Allows you to configure source-scope options that you usually specify in an Ultra Messaging configuration file or set using lbm_*_attr_setopt(). For example, you could change the transport by including the following within the '<ume-attributes> ' element: <option type="lbm-source" name="transport" value="lbtru"/> ' <option> ' is a child of '<ume-attributes> ', but you can use option type lbm-source within only a '<topic> ' element, not a '<store> ' element. | None - this is a required attribute. |
store | Option type used for all ume-attributes configured for the store element and its topic element. | None - this is a required attribute. |
The DTD for UM Store configuration has evolved over time:
DTD Version | Release Date | Product Version | Supported Features |
---|---|---|---|
1.0 | Feb. 2007 | UME 1.0 | Persistent Stores |
1.1 | April 2010 | UME 3.0.1 / UMQ 1.0 | Persistent Stores, Queues and Ultra Load Balancing (ULB) |
1.2 | March 2011 | UME 3.2 / UMQ 2.1 | Persistent Stores, Queues, Ultra Load Balancing (ULB), Dead Letter Queue, Indexed Queuing and Indexed ULB |
1.3 | November 2016 | UM 6.10 | Addition of '<xml-config> ' element (under '<daemon> '). |
Here is the current version:
Store daemon with one store.
The '<xml-config>
' tag is used to load a UM configuration file which is used by the store as it creates UM objects (contexts, receivers, etc.). This example applies the configuration specified in the "tnwgd" application tag of the file "lbm_cfg.xml":
If an 'application-name
' attribute is not supplied, "umestored" is assumed. If it is desired to load the unnamed configuration, use an empty application name as follows: