Chapter 7. Resource Limits and Policies

You can define resource limits and policies to control important aspects of how the broker instance should handle messages. The process for configuring these resource limits and policies is different in AMQ Broker 7 than in AMQ 6, and many of the configuration properties have changed.

7.1. How Resource Limits and Policies Are Configured

In AMQ 6, resource limits and policies were configured as destination policies in the broker’s configuration file.

In AMQ Broker 7, you define resource limits and policies for an address or set of addresses. When the broker instance receives a message, the resource limits and policies defined for the message’s address are applied to the message.

To configure resource limits and policies in AMQ Broker 7, you use the BROKER_INSTANCE_DIR/etc/broker.xml configuration file to define <address-setting> elements with the appropriate configuration properties.

The broker.xml configuration file contains the following default address settings configuration:

<address-settings>
    <!-- if you define auto-create on certain queues, management has to be auto-create -->
    <address-setting match="activemq.management#"> 1
        <dead-letter-address>DLQ</dead-letter-address>
        <expiry-address>ExpiryQueue</expiry-address>
        <redelivery-delay>0</redelivery-delay>
        <!-- with -1 only the global-max-size is in use for limiting -->
        <max-size-bytes>-1</max-size-bytes>
        <message-counter-history-day-limit>10</message-counter-history-day-limit>
        <address-full-policy>PAGE</address-full-policy>
        <auto-create-queues>true</auto-create-queues>
        <auto-create-addresses>true</auto-create-addresses>
        <auto-create-jms-queues>true</auto-create-jms-queues>
        <auto-create-jms-topics>true</auto-create-jms-topics>
    </address-setting>
    <!--default for catch all-->
    <address-setting match="#"> 2
        <dead-letter-address>DLQ</dead-letter-address>
        <expiry-address>ExpiryQueue</expiry-address>
        <redelivery-delay>0</redelivery-delay>
        <!-- with -1 only the global-max-size is in use for limiting -->
        <max-size-bytes>-1</max-size-bytes>
        <message-counter-history-day-limit>10</message-counter-history-day-limit>
        <address-full-policy>PAGE</address-full-policy>
        <auto-create-queues>true</auto-create-queues>
        <auto-create-addresses>true</auto-create-addresses>
        <auto-create-jms-queues>true</auto-create-jms-queues>
        <auto-create-jms-topics>true</auto-create-jms-topics>
    </address-setting>
</address-settings>
1
The default management address setting. The nested resource limits and policies are applied to all messages with an address that matches activemq.management#.
2
The default address setting. The # wildcard matches all addresses, so the defined resource limits and policies are applied to all messages.

To configure resource limits and policies, you specify an address or set of addresses (using <address-setting>), and then add resource limit and policy properties to it. These properties are applied to each message sent to the address (or addresses) that you specified.

Related Information

7.2. Resource Limit and Policy Configuration Properties

Like AMQ 6, in AMQ Broker 7, you can add resource limits and policies to control how the broker handles certain aspects of how and when messages are delivered, the number of delivery attempts that should be made, and when messages should expire. However, the configuration properties you use to define these resource limits and policies are different in AMQ Broker 7.

This section compares the <policyEntry> configuration properties in AMQ 6 to the equivalent <address-setting> properties in AMQ Broker 7. For complete details on each configuration property in AMQ Broker 7, see Address Setting Configuration Elements in Using AMQ Broker.

7.2.1. Queue Management Configuration Properties

The following table compares the queue management configuration properties in AMQ 6 to the equivalent properties in AMQ Broker 7:

To set…​In AMQ 6In AMQ Broker 7

The memory limit

memoryLimit

Sets a memory limit for the destination. The default is none.

<max-size-bytes>

Sets the memory limit for the address. The default is -1 (no limit).

The order of the messages by priority within the queue

prioritizedMessages

This is off by default, which means that messages are prioritized on the consumer (not the broker), and therefore are ordered based on the priorities of the messages on the consumer.

Messages are automatically ordered by priority within the queue.

How often the broker should scan for expired messages

expiredMessagesPeriod

<message-expiry-scan-period>

The default is 30000 ms.

Whether the broker should delete destinations that are inactive for a period of time

gcInactiveDestinations

The default is false.

No equivalent. However, for automatically-created queues, you can set the queue to be automatically deleted when the last consumer is detached. For more information, see Creating and Deleting Queues and Addresses Automatically in Using AMQ Broker.

The inactive timeout

inactiveTimeoutBeforeGC

The default is 60 seconds.

No equivalent. However, for automatically-created queues, you can set the queue to be automatically deleted when the last consumer is detached. For more information, see Creating and Deleting Queues and Addresses Automatically in Using AMQ Broker.

Whether the broker should use a separate thread when dispatching from a queue

optimizedDispatch

The default is false.

This cannot be set for an address or queue. However, you can control it from the incoming connection on which the message arrives. Use the directDeliver property on an acceptor or connector to control whether the message should be delivered on the same thread on which it arrived. For more information, see Acceptor and Connector Configuration Parameters in Using AMQ Broker.

7.2.2. Producer Policy Configuration Properties

The following table compares the producer policy configuration properties in AMQ 6 to the equivalent properties in AMQ Broker 7:

To set…​In AMQ 6In AMQ Broker 7

Producer flow control

producerFlowControl

Sets the broker to throttle the producer. The throttling is achieved by either withholding the producer’s acknowledgement, or by raising a javax.jms.ResourceAllocationException exception and propagating it back to the client when local resources have been exhausted (such as memory or storage). The default is true.

For the address, set <max-size-bytes> to the size at which the producer should be throttled, and then set <address-full-policy> to BLOCK.

Configuring these two properties will also throttle your existing AMQ 6 OpenWire producers.

The amount of credits a producer can request at one time

No equivalent.

<producer-window-size>

Limiting the window size sets a limit on the number of bytes that the producer can have "in-flight" at any one time, which can prevent the remote connection from becoming overloaded.

7.2.3. Consumer Policy Configuration Properties

The following table compares the server-side destination policy configuration properties in AMQ 6 to the equivalent properties in AMQ Broker 7. These properties only apply to OpenWire clients:

To set…​In AMQ 6In AMQ Broker 7

The queue prefetch

queuePrefetch

No equivalent on the broker. However, you can set the maximum size of messages (in bytes) that will be buffered on a consumer by setting the consumerWindowSize on the connection URL or directly on the ActiveMQConnectionFactory API.

Whether to use the priority of a consumer when dispatching messages from a queue

useConsumerPriority

The default is true.

This functionality does not exist in AMQ Broker 7.

Whether to use the prefetch extension to enable the broker to dispatch "prefetched" messages when the previous message is delivered but not acknowledged

usePrefetchExtension

The default is true.

This functionality does not exist in AMQ Broker 7.

Initial redelivery delay

initialRedeliveryDelay

The default is 1000 ms.

No equivalent. The broker instance automatically handles this.

How long to wait before attempting to redeliver a canceled message

redeliveryDelay

The delivery delay if initialRedeliveryDelay is set to 0. The default is 1000 ms.

<redelivery-delay>

The default is 0 ms.

Exponential back-off

useExponentialBackoff

The default is false.

No equivalent. You can use any of the other consumer policy configuration properties to configure redelivery for a consumer.

Backoff multiplier

backOffMultiplier

The default is 5.

<redelivery-multiplier>

The multiplier to apply to the redelivery delay. The default is 1.0.

The maximum number of times a cancelled message can be redelivered before it is returned to the broker’s Dead Letter Queue

maximumRedeliveries

The default is 6.

<max-delivery-attempts>

The default is 10.

The maximum value for the redelivery delay

maximumRedeliveryDelay

This is only applied if the useExponentialBackoff property is set. The default is -1 (no maximum redelivery delay).

<max-redelivery-delay>

The default is 0.

The number of messages that a client can consume in a second

No equivalent.

No equivalent on the broker. However, you can set this on a consumer by setting the consumerMaxRate on the connection URL or directly on the ActiveMQConnectionFactory API.

The consumerMaxRate property does not affect the number of messages that a client has in its buffer. Therefore, if the client has a slow rate limit and a high window size, the client’s internal buffer would quickly fill up with messages.

7.2.4. Slow Consumer Handling Configuration Properties

Like AMQ 6, AMQ Broker 7 can detect slow consumers and automatically stop the ones that are consistently slow. This was enabled by default in AMQ 6, but is disabled by default in AMQ Broker 7.

The way in which the broker determines that a consumer is "slow" is also different. In AMQ Broker 7, a consumer is considered to be slow based on the number of messages the consumer has acknowledged. In AMQ 6, a consumer was considered to be slow based on the fullness of the prefetch buffer (if the buffer is consistently full, then the client may be consuming messages too slowly).

The following table compares the slow consumer handling configuration properties in AMQ 6 to the equivalent properties in AMQ Broker 7:

To set…​In AMQ 6In AMQ Broker 7

The number of times a consumer can be considered to be slow before it is aborted

maxSlowCount

The default is -1 (no limit).

No equivalent. You can use the other slow consumer handling properties to control slow consumers.

The amount of time a consumer can be continuously slow before it is aborted

maxSlowDuration

The default is 30000 ms.

<slow-consumer-threshold>

In AMQ Broker 7, this is the minimum rate of message consumption before a consumer is considered to be "slow" (measured in messages per second). The default is -1 (no threshold).

The amount of time the broker should wait before performing another check for slow consumers

checkPeriod

The default is 30000 ms.

<slow-consumer-check-period>

In AMQ Broker 7, this is measured in seconds. The default is 5.

Whether the broker should close the connection along with a slow consumer

abortConnection

The default is false.

No equivalent. In AMQ Broker 7, when a slow consumer is aborted, the connection is also closed.

The policy to apply if a slow consumer is detected.

No equivalent.

<slow-consumer-policy>

The default is NOTIFY, which will send a CONSUMER_SLOW management notification to the application.

You can also use the KILL policy to close the consumer’s connection. However, this will impact any other client threads using that connection.

Related Information

7.2.5. Message Paging Configuration Properties

In AMQ Broker 7, the process by which the broker stores messages in memory and stores them to disk is significantly different than AMQ 6. Therefore, most of the paging configuration properties in AMQ 6 do not apply to AMQ Broker 7.

In AMQ Broker 7, paging is configured on message addresses. Each address is configured to use a maximum number of bytes. When this limit is reached, messages sent to that address are paged to an on-disk buffer before they reach their queues. The queues are de-paged one page at a time when the address has enough available space.

The following table compares the message paging size limits in AMQ 6 to the equivalent properties in AMQ Broker 7:

To set…​In AMQ 6In AMQ Broker 7

The paging size

maxPageSize

This is measured in number of messages, and is variable based on the number of available messages.

<page-size-bytes>

This is measured in the physical page size in bytes (not messages).

7.2.6. Dead Letter Policy Configuration Properties

AMQ Broker 7 handles undeliverable and expired messages much differently than AMQ 6. Dead letter policies are applied to addresses (instead of destinations), there are separate dead letter and expiry destinations (instead of a single dead letter queue), and the dead letter policy configuration is significantly different.

Dead Letter Policies in AMQ 6

In AMQ 6, an expired or undeliverable message would be sent to the dead letter queue (DLQ) configured for each message’s destination. To configure the DLQ for a destination, you could use any of the following dead letter policies:

sharedDeadLetterStrategy
The destination’s undeliverable messages are sent to the shared, default DLQ called ActiveMQ.DLQ.
individualDeadLetterStrategy
The destination’s undeliverable messages are sent to a dedicated DLQ for this destination.
discardingDeadLetterStrategy
The destination’s undeliverable messages are discarded.

Within a destination’s dead letter policy, you could add the following configuration properties to control the types of messages that should be sent to the destination’s DLQ:

AMQ 6 Configuration PropertyDescription

processNotPersistent

Whether non-persistent messages should be sent to the destination’s DLQ. The default is false.

processExpired

Whether expired messages should be sent to the destination’s DLQ. The default is true.

expiration

Whether an expiry should be applied to the messages sent to the destination’s DLQ. The default is 0.

Dead Letter Policies in AMQ 7

In AMQ Broker 7, undeliverable messages are sent to the applicable dead letter address, and expired messages are sent to the applicable expiry address.

In the broker.xml configuration file, the default address setting specifies a dead letter address and expiry address. Undeliverable and expired messages will be delivered to the destinations specified by these settings:

...
<address-settings>
    <address-setting match="#">
        <dead-letter-address>DLQ</dead-letter-address>
        <expiry-address>ExpiryQueue</expiry-address>
        ...
    </address-setting>
    ...
</address-settings>
...

By default, the dead letter and expiry addresses specify the DLQ and ExpiryQueue destinations, which are defined in the <addresses> section:

...
<addresses>
    <address name="DLQ">
        <anycast>
            <queue name="DLQ" />
        </anycast>
    </address>
    <address name="ExpiryQueue">
        <anycast>
            <queue name="ExpiryQueue" />
        </anycast>
    </address>
...
</addresses>
...

To configure a non-default dead letter policy for an address, you can add a <dead-letter-address> and <expiry-address> to the address’s <address-setting> and specify the DLQ and expiry queue it should use.

Unlike AMQ 6, in AMQ Broker 7, you cannot set an expiry time on messages sent to the DLQ. In addition, both persistent and non-persistent messages are sent to the DLQ specified by the address’s <dead-letter-address>.