2.2. Configuring the KahaDB Message Store

Overview

Red Hat JBoss A-MQ's default configuration includes a persistence adapter that uses a KahaDB message store. The default configuration is suitable for many use cases, but you will likely want to update it for individual broker instances. You do this using the attributes of the kahaDB element.
The basic configuration tells the broker where to write the data files used by the store.
The KahaDB message store also has a number of advanced configuration attributes that customize its behavior.

Basic configuration

The KahaDB message store is configured by placing a kahaDB element in the persistenceAdapter element of your broker's configuration. The kahaDB element's attributes are used to configure the message store.
The attributes, listed in Table 2.1, “Configuration Properties of the KahaDB Message Store”, all have reasonable default values, so you are not required to specify values for them. However, you will want to explicitly specify the location of the message store's data files by providing a value for the directory attribute. This will ensure that the broker will not conflict with other brokers.
Example 2.1, “Configuring the KahaDB Message Store” shows a basic configuration of the KahaDB message store. The KahaDB files are stored under the activemq-data directory.

Example 2.1. Configuring the KahaDB Message Store

<broker brokerName="broker" persistent="true" ... >
  ...
  <persistenceAdapter>
    <kahaDB directory="activemq-data" />
  </persistenceAdapter>
  ...
</broker>

Configuration attributes

Table 2.1, “Configuration Properties of the KahaDB Message Store” describes the attributes that can be used to configure the KahaDB message store.

Table 2.1. Configuration Properties of the KahaDB Message Store

AttributeDefault ValueDescription
archiveCorruptedIndex falseSpecifies if corrupted indexes are archived when the broker starts up.
archiveDataLogs falseSpecifies if the message store moves spent data logs to the archive directory.
checkForCorruptJournalFiles falseSpecifies whether the message store checks for corrupted journal files on startup and tries to recover them.
checkpointInterval 5000Specifies the time interval, in milliseconds, between writing the metadata cache to disk.
checksumJournalFiles trueSpecifies whether the message store generates a checksum for the journal files. If you want to be able to check for corrupted journals, you must set this property to true.
cleanupInterval30000Specifies the time interval, in milliseconds, between cleaning up data logs that are no longer used.
compactAcksAfterNoGC 10When the acknowledgement compaction feature is enabled, specifies how many store GC cycles must be completed without cleaning up other files before the compaction logic is triggered to possibly compact older acknowledgements spread across journal files into a new log file. The lower the value set the faster the compaction may occur which can impact performance if it runs often.
compactAcksIgnoresStoreGrowth falseWhen the acknowledgement compaction feature is enabled, specifies whether compaction is run when the store is still growing or if it should only occur when the store has stopped growing (either due to idle or store limits reached). If enabled the compaction runs regardless of the store still having room or being active which can decrease overall performance but reclaim space faster.
concurrentStoreAndDispatchQueuestrueSpecifies if the message store dispatches queue messages to clients concurrently with message storage. See Section 2.3, “Concurrent Store and Dispatch”.
concurrentStoreAndDispatchTopicsfalseSpecifies if the message store dispatches topic messages to interested clients concurrently with message storage. See Section 2.3, “Concurrent Store and Dispatch”. Enabling this property is not recommended. It is disabled by default because it can lead to stuck or duplicate messages and its real value is small when there are multiple durable consumers, it is unlikely that all of them will have acked before the store.
databaseLockedWaitDelay10000Specifies the time delay, in milliseconds, before trying to acquire the database lock in the context of a shared master/slave failover deployment. See section "Shared File System Master/Slave" in "Fault Tolerant Messaging".
directoryactivemq-dataSpecifies the path to the top-level folder that holds the message store's data files.
directoryArchivenullSpecifies the location of the directory to archive data logs.
enableAckCompaction falseSpecifies whether the store will perform periodic compaction of older journal log files that contain only Message acknowledgements. After compacting the older acknowledgements into new journal log files, the older files can be removed. This action frees the space and allows the message store to continue to operate without hitting store size limits.
enableIndexDiskSyncstrueEnsures index updates are persisted to the disk on each write.
enableIndexPageCachingtrueEnables faster reads by caching the written pages in the memory.
enableIndexRecoveryFiletrueEnabled double write of index updates, allowing the index to recover from partial write failures.
enableIndexWriteAsyncfalseSpecifies if kahaDB will asynchronously write indexes.
enableJournalDiskSyncstrueSpecifies whether every non-transactional journal write is followed by a disk sync. If you want to satisfy the JMS durability requirement, you must also disable concurrent store and dispatch.
failoverProducersAuditDepth Set the audit window depth for duplicate suppression (should exceed the max transaction batch).
forceRecoverIndexfalseThis option is only used in specific upgrade scenarios. In normal scenarios, this can be ignored.
ignoreMissingJournalfilesfalseSpecifies whether the message store ignores any missing journal files while it starts up. If false, the message store raises an exception when it discovers a missing journal file.
indexCacheSize10000Specifies the number of B-tree index pages cached in memory.
indexDirectory Set this attribute, if you need to store the index file (metadata store), db.data, in a different location from the other message store data files. By default, the index is stored in the same location as the other message store files.
indexWriteBatchSize1000Specifies the number of B-tree indexes written in a batch. Whenever the number of changed indexes exceeds this value, the metadata cache is written to disk.
journalMaxFileLength32mbSpecifies the maximum size of the data log files.
journalMaxWriteBatchSize4kSpecifies the amount of data to buffer between journal disk writes. Optimize to match the fastest write size for your disk.
lockKeepAlivePeriod In the context of a master/slave broker cluster, instructs the master to check, at intervals of the specified milliseconds, whether it still holds the lock (lock is valid) and that the lock file still exists.
locker  
maxAsyncJobs10000Specifies the size of the task queue used to buffer the broker commands waiting to be written to the journal. The value should be greater than or equal to the number of concurrent message producers. See Section 2.3, “Concurrent Store and Dispatch”.
maxFailoverProducersToTrack Set the maximum number of producers (LRU cache) to track for duplicate sends.
preallocationStrategy sparse_fileSpecifies how the broker will try to preallocate the journal files when a new journal file is needed. The default allocation strategy sets the file length, but does not populate it with any data. The os_kernel_copy strategy delegates the preallocation to the Operating System. The zeros strategy configures ActiveMQ to do the preallocation by writing 0x00 to all of the positions in the journal file.
preallocationScope entire_journalSpecifies how the broker will preallocate the journal data files. The default preallocates on first use in the appender thread. entire_journal_async will use preallocate ahead of time in a separate thread. none disables preallocation. On SSD, using entire_journal_async avoids delaying writes pending preallocation on first use. On HDD the additional thread contention for disk has a negative impact, hence it is advisable to use the default.
storeOpenWireVersion 11Determines the version of OpenWire commands that are marshalled to the KahaDB journal.
useIndexLFRUEviction  
useLocktrueSpecifies whether the adapter uses file locking.