Configuring Key/Value Pair Stores
The eMessage Connector provides Key/Value Pair (KVP) stores. These stores are generic, limited in size, and limited in the amount of time that a key/value pair remains in the store. If the size limit is reached, the Least Recently Used (LRU) key/value pair is removed from the store. If the time limit is reached, the least recently used (LRU) key/value pair is removed from the store.
The following stores (stashes and caches) are available with the eMessage Connector:
• ThingNameStash — Stores the names of Things that exist on the ThingWorx Platform for the edge devices that are running an eMessage Agent (Axeda Gateway and Axeda Connector) that communicates with ThingWorx Platform through an eMessage Connector. The Platform-side name of a Thing is relative to an edgeIdentifier that uniquely identifies the physical device at the edge.
• EgressAckEventStash — Stores the events that occur to acknowledge that the eMessage Connector has received egress messages from the ThingWorx Platform. This stash allows the coordination of the handling of egress commands that are destined for edge devices with acknowledgements of those commands from the edge devices.
• SecurityClaimsStash — Stores the results of token authentication requests to the ThingWorx platform. If authentication fails, the exception field is set. Otherwise, the exception field is null.
• UploadFileMetadataCache — Stores mappings of the identifiers associated with transfer jobs (transferId) to their metadata for purposes of tracking the state of the job over the life of a file upload.
• DownloadSessionCache — Stores all the request parameters from the Copy service for file downloads. It stores these parameters by sessionId.
 |
In ThingWorx, the identifier for a file transfer job is called the transferId. Axeda Enterprise Server has a corresponding concept that is called the sessionId. eMessage Connector reuses the transferId from ThingWorx as the Axeda sessionId. Essentially, for the Connector, the transferId and the sessionId are the same.
|
• FileTransferSubsystemConfigCache — The ThingWorx Platform FileTransfer Subsystem defines a maxFileSize configuration option (in bytes). The eMessage Connector will get the maxFileSize configuration value from the platform and cache it in the FileTransferSubsystemConfigCache, using maxFileSize as a key.
Two properties are available to configure the size and time limits for each of these stores. By default, the eMessage Connector uses default values for all stores when it does not find values for a given store. The default properties and values for all stores are:
• default-max-keys — The maximum number of key/value pairs that can exist in the stores. The default value is 100,000 key/value pairs.
• default-expire-time — The number milliseconds that each key/value pair can remain in a store before it is removed from the store. The hard-coded, default value is one day (86,400,000 ms). This value is used for specific stores if no other value is configured (expire-time property value is blank).
The properties for each of the stores are:
• max-keys — The maximum number of key/value pairs that can exist in the given store. The default value for every store is 100,000 key/value pairs.
• expire-time — The number of milliseconds that each key/value pair can remain in a store before it is removed from the store. The default value varies for different stores. The range is from five minutes to one day (300,000 to 86,400,000 ms). If there is no configured value, the eMessage Connector uses the hard-coded default value of 86,400,000 ms (one day). Note that a value of -1 means that the key/value pairs never expire; this setting is NOT recommended. Any number lower than -1 causes the eMessage Connector to fail to start. For a table of the default values for this property for all the KVP stores, refer to the table below,Table 18
 |
Do NOT attempt to change these settings unless you know what you are doing. For advice about setting values for these properties, refer to Tips for
Choosing Values for the Stashes of the KVP Store. Warning messages will appear if the defaults for all caches are not set properly or if the caches are configured to be essentially unbounded. Refer to Warning
Messages for a list of these messages.
|
To configure the KVP stores:
1. Using a text editor, open your configuration file. If you used the sample emessage.conf as the starting point for your configuration file, all of the stashes are included in your configuration file.
2. Locate the group, store. Note that if this group was not present in your configuration file, the eMessage Connector uses the default settings for ALL stores (as described above).
3. First, configure the two properties that apply to any store that does not have them set explicitly. The following example changes the default value of the default-expire-time but leaves the default value for the maximum number of keys:
store = {
default-max-keys = 100000
default-expire-time = 1800000
default-max-keys = 100000
default-expire-time = 1800000
|
|
Keep in mind that these global settings are used if you do not configure settings for individual stores. The unit of measure for default-expire-time is a number of milliseconds. In the example above, the number of milliseconds converts to 30 minutes.
|
4. Set these properties for the ThingNameStash. The following example sets the maximum number of keys to 80,000, and sets the expiration time to one day (86,400,000 ms):
ThingNameStash = {
max-keys = 80000,
expire-time = 86400000
}
max-keys = 80000,
expire-time = 86400000
}
5. Set these properties for the EgressAckEventStash. By NOT setting the max-keys property, the following example keeps the default maximum number of keys (100,000). It sets the expiration time to 10 minutes (600,000 ms):
EgressAckEventStash = {
expire-time = 600000
}
expire-time = 600000
}
6. Set these properties for the SecurityClaimsStash. The following example sets the maximum number of keys to 80,000 and the expiration time to 15 minutes (900,000 ms):
SecurityClaimsStash = {
max-keys = 80000,
expire-time = 900000
}
max-keys = 80000,
expire-time = 900000
}
7. Set these properties for the UploadFileMetadataCache. The following example sets the maximum number of keys to 50,000 and the expiration time to 5 minutes (300,000 ms):
UploadFileMetadataCache = {
max-keys = 50000,
expire-time = 300000
}
max-keys = 50000,
expire-time = 300000
}
8. Set these properties for the DownloadSessionCache. The following example sets the maximum number of keys to 50,000 and the expiration time to 10 minutes (600,000 ms):
DownloadSessionCache = {
max-keys = 50000,
expire-time = 600000
}
max-keys = 50000,
expire-time = 600000
}
9. Set the properties for the FileTransferSubsystemConfigCache:
FileTransferSubsystemConfigCache = {
max-keys = 10,
expire-time = 3600000
}
max-keys = 10,
expire-time = 3600000
}
|
|
If you change the maxFileSize configuration option of the File Transfer Subsystem, you need to clear the maxFileSize configuration value from the FileTransferSubsystemConfigCache on all the eMessage Connectors. For instructions, refer to Restricting the Maximum File Size for File Transfers.
|
10. Save your configuration file.
11. At this point, you have the following options:
◦ To set the properties for file transfers, continue to the next section, Configuring File Transfers. Make sure that you also configure the File Transfer Subsystem of the ThingWorx Platform so that file transfers for eMessage agents are queue-able.
◦ As long as you have previously set the environment variable and started the eMessage Connector, restart the eMessage Connector.
◦ If you have not set the environment variable, go to Setting the Environment Variable and set it, and then to Starting the eMessage Connector and Running a Quick Test to start the eMessage Connector and run a quick test for connectivity to the ThingWorx Platform.
Tips for Choosing Values for the Stashes of the KVP Store
The values to use for any given stash depend on the types and scale of the devices being serviced by the eMessage Connector. In some cases, allowing the settings for a cache to fall back to the default values for the max-keys and expire-time properties is appropriate.
However, there are some best practices to follow for deciding how many keys to allow in the cache and how often they should be removed. The goal is to maintain a balance between how many requests are being made to the ThingWorx Platform for each cache without allowing the caches to starve the rest of the application of memory.
Expire Time
To decide on an appropriate expire-time for cache key/value pairs, analyze the frequency of traffic for any given device that communicates with the Connector. If devices communicate frequently (every minute, for example), a good strategy would be to set expire-time to something longer so the key/value pair does not expire for each message. For devices that communicate less frequently, it may be better to leave the expire-time short so the key/value pairs do not take up memory for long periods during which the device is not communicating.
Max Keys
Choosing a value for max-keys requires more analysis of the total number of devices that will be communicating and the environment in which the Connector is running. For instance, if you have 100,000 assets communicating and set max-keys to 1,000, it is likely that pairs will be removed from the cache often, leading to additional traffic to the ThingWorx Platform when those devices that were removed communicate again. However, setting max-keys arbitrarily high can lead to resource issues for the application as the device load increases.
To help you with this configuration, here is a table that shows the default settings for all of the KVP store for the expire-time property. The default value for max-keys for all stores is 100,000.
|
KVP Store
|
expire-time
|
|---|---|
|
ThingNameStash
|
-1 Note that the content of this KVP store rarely changes, so no expiration time is needed.
|
|
EgressAckEventStash
|
300000 (five minutes)
|
|
TokenAuthenticationCache
|
1800000 (30 minutes)
|
|
UploadFileMetadataCache
|
300000 (five minutes)
|
|
DownloadSessionCache
|
86400000 (one day)
|
Warning Messages
By default, eMessage Connector uses the default cached sizes if no default is specified in the configuration file. When values are specified, they are validated. A warning is issued if the sizes are manually set to UNBOUNDED or 0 or a negative value. The following table lists and describes these messages.
|
Warning Message
|
Description
|
|---|---|
|
There is no default-max-keys specified for the caches. The system default will be used if there is no override value specified for each cache. The system default of 100,000 will be used if there is no override value specified for each cache.
|
No default-max-keys is configured. The default setting is 100,000 keys and will be used. This warning should never occur because the Connector has a default value that it uses if no configuration for the stores exists. However, if you add the property name but leave the value empty in the configuration file, this warning will appear.
|
|
There is no default-expire-time specified for the caches. The system default of 86,400,000 ms (1 day) will be used if there is no override expire-time value specified for each cache.
|
No default-expire-time is configured. The default setting is 86,400,000 ms (1 day in milliseconds) and will be used. This warning should never occur because the Connector has a default value that it uses if no configuration for the stores exists. However, if you add the property name but leave the value empty in the configuration file, this warning will appear.
|
|
Max key size: value for cache: cache name is essentially unbounded. Consider setting default-max-keys or the cache max-keys to a lower value
|
The maximum key size for a particular cache is unbounded. This warning will occur if an override for max-keys or default-max-keys is specified with a value of 0 or 2,147,483,647.
|
|
The contents of cache: cache name will never expire: -1. Consider setting default-expire-time or the cache expire-time.
|
The entries of cache name will never expire. This warning occurs if an override for expire-time or default-expire-time is specified with a value of -1. Set a value for all caches or a specific value for cache name.
|