| <?xml version="1.0"?> |
| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| --> |
| |
| <section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Qpid-Producer-Flow-Control"> |
| <title>Producer Flow Control</title> |
| |
| <section role="h2" xml:id="Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control-GeneralInformation"> |
| <title>General Information</title> |
| <para> |
| The Apache Qpid Broker for Java supports a flow control mechanism to which can be used to prevent either a single queue |
| or a virtualhost exceeding configured limits. These two mechanisms are described |
| next. |
| </para> |
| </section> |
| <section role="h2" xml:id="Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control-ServerConfiguration"> |
| <title>Server Configuration</title> |
| <section role="h3"> |
| <title>Configuring a Queue to use flow control</title> |
| <para> |
| Flow control is enabled on a producer when it sends a message to a Queue |
| which is "overfull". The producer flow control will be rescinded when all |
| Queues on which a producer is blocking become "underfull". A Queue is defined |
| as overfull when the size (in bytes) of the messages on the queue exceeds the |
| <emphasis>capacity</emphasis> of the Queue. A Queue becomes "underfull" when its |
| size becomes less than the <emphasis>resume capacity</emphasis>. |
| </para> |
| <para> |
| The capacity and resume capacity can be specified when the queue is created. This |
| can be done using the Flow Control Settings within the Queue creation dialogue. |
| </para> |
| <section role="h4"> |
| <title>Broker Log Messages</title> |
| <para> |
| There are four Broker log messages that may occur if flow control through queue capacity limits is enabled. |
| Firstly, when a capacity limited queue becomes overfull, a log message similar to the following is produced |
| </para> |
| <programlisting> |
| MESSAGE [vh(/test)/qu(MyQueue)] [vh(/test)/qu(MyQueue)] QUE-1003 : Overfull : Size : 1,200 bytes, Capacity : 1,000 |
| </programlisting> |
| <para>Then for each channel which becomes blocked upon the overful queue a log message similar to the following is produced:</para> |
| <programlisting> |
| MESSAGE [con:2(guest@anonymous(713889609)/test)/ch:1] [con:2(guest@anonymous(713889609)/test)/ch:1] CHN-1005 : Flow Control Enforced (Queue MyQueue) |
| </programlisting> |
| <para>When enough messages have been consumed from the queue that it becomes underfull, then the following log is generated: </para> |
| <programlisting> |
| MESSAGE [vh(/test)/qu(MyQueue)] [vh(/test)/qu(MyQueue)] QUE-1004 : Underfull : Size : 600 bytes, Resume Capacity : 800 |
| </programlisting> |
| <para>And for every channel which becomes unblocked you will see a message similar to: </para> |
| <programlisting> |
| MESSAGE [con:2(guest@anonymous(713889609)/test)/ch:1] [con:2(guest@anonymous(713889609)/test)/ch:1] CHN-1006 : Flow Control Removed |
| </programlisting> |
| <para>Obviously the details of connection, virtual host, queue, size, capacity, etc would depend on the configuration in use.</para> |
| |
| |
| </section><!-- Broker Log Messages --> |
| </section><!-- Configuring a Queue to use flow control --> |
| |
| <section role="h3"> |
| <title>Disk quota-based flow control</title> |
| <para> |
| Flow control can also be triggered when a configured disk quota is exceeded. This is supported by the BDB and |
| Derby virtualhosts. |
| </para> |
| <para> |
| This functionality blocks all producers on reaching the disk overflow limit. When consumers |
| consume the messages, causing disk space usage to falls below the underflow limit, the |
| producers are unblocked and continue working as normal. |
| </para> |
| <para> |
| Two limits can be configured: |
| </para> |
| <para> |
| overfull limit - the maximum space on disk (in bytes). |
| </para> |
| <para> |
| underfull limit - when the space on disk drops below this limit, producers are allowed to resume publishing. |
| </para> |
| |
| <para> |
| The overfull and underful limit can be specified when a new virtualhost is created or an exiting |
| virtualhost is edited. This can be done using the Store Overflow and Store Underfull settings |
| within the virtual host creation and edit dialogue. If editing an existing virtualhost, the virtualhost |
| must be restarted for the new values to take effect. |
| </para> |
| |
| <para> |
| The disk quota functionality is based on "best effort" principle. This means the broker |
| cannot guarantee that the disk space limit will not be exceeded. If several concurrent |
| transactions are started before the limit is reached, which collectively cause the limit |
| to be exceeded, the broker may allow all of them to be committed. |
| </para> |
| |
| <para> |
| The Broker will also impose flow control if the filesystem hosting a virtualhost |
| exceeds a <link linkend="Java-Broker-Management-Managing-Broker-Context-StoreFilesystemMaxUsagePercent"> |
| configured percentage.</link>. |
| </para> |
| |
| <section role="h4"> |
| <title>Broker Log Messages for quota flow control</title> |
| <para> |
| There are two broker log messages that may occur if flow control through disk quota limits is enabled. |
| When the virtual host is blocked due to exceeding of the disk quota limit the following message |
| appears in the broker log |
| <programlisting> |
| [vh(/test)/ms(BDBMessageStore)] MST-1008 : Store overfull, flow control will be enforced |
| </programlisting> |
| When virtual host is unblocked after cleaning the disk space the following message appears in the broker log |
| <programlisting> |
| [vh(/test)/ms(BDBMessageStore)] MST-1009 : Store overfull condition cleared |
| </programlisting> |
| </para> |
| </section> |
| </section><!-- Disk quota-based flow control --> |
| </section><!-- Server configuration --> |
| |
| |
| <section role="h2" xml:id="Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control-ClientImpact"> |
| <title>Client impact and configuration</title> |
| <para> |
| If a producer sends to a queue which is overfull, the broker will respond by |
| instructing the client not to send any more messages. The impact of this is |
| that any future attempts to send will block until the broker rescinds the flow control order. |
| </para> |
| <para> |
| While blocking the client will periodically log the fact that it is blocked waiting on flow control. |
| </para> |
| <programlisting> |
| WARN Message send delayed by 5s due to broker enforced flow control |
| WARN Message send delayed by 10s due to broker enforced flow control |
| </programlisting> |
| <para> |
| After a set period the send will timeout and throw a JMSException to the calling code. |
| </para> |
| <para> |
| If such a JMSException is thrown, the message will not be sent to the broker, |
| however the underlying Session may still be active - in particular if the |
| Session is transactional then the current transaction will not be automatically |
| rolled back. Users may choose to either attempt to resend the message, or to |
| roll back any transactional work and close the Session. |
| </para> |
| <para> |
| Both the timeout delay and the periodicity of the warning messages can be set |
| using Java system properties. |
| </para> |
| <para> |
| The amount of time (in milliseconds) to wait before timing out |
| is controlled by the property qpid.flow_control_wait_failure. |
| </para> |
| <para> |
| The frequency at which the log message informing that the producer is flow |
| controlled is sent is controlled by the system property qpid.flow_control_wait_notify_period. |
| </para> |
| <para> |
| Adding the following to the command line to start the client would result in a timeout of one minute, |
| with warning messages every ten seconds: |
| </para> |
| <programlisting> |
| -Dqpid.flow_control_wait_failure=60000 |
| -Dqpid.flow_control_wait_notify_period=10000 |
| </programlisting> |
| </section> <!-- Client impact and configuration --> |
| </section> |