qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Qpid > Use Producer Flow Control
Date Tue, 16 Oct 2012 07:54:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/21/_/styles/combined.css?spaceKey=qpid&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/qpid/Use+Producer+Flow+Control">Use
Producer Flow Control</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~k-wall">keith
wall</a>
    </h4>
        <br/>
                         <h4>Changes (2)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{info}
<br>This page applies to Java Broker versions before 0.18. For the master copy of this
documentation see the Producer Flow Control section in the  [Java  documentation|http://qpid.apache.org/documentation.html]
<br>{info} <br> <br></td></tr>
            <tr><td class="diff-unchanged" >{toc} <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >The Qpid Java Broker 0.6 release introduces
a simplistic producer-side flow control mechanism into the Java Messaging Broker, causing
producers to be flow-controlled when they attempt to send messages to an overfull queue or
overfull message store on a virtual host. <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">*Note:*
from version 0.18, the master copy of this documentation is in the [AMQP Messaging Broker
book| http://qpid.apache.org/documentation.html#doc-release]. <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h2. Server configuration <br>
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <div class='panelMacro'><table class='infoMacro'><colgroup><col
width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/information.gif"
width="16" height="16" align="absmiddle" alt="" border="0"></td><td>This page
applies to Java Broker versions before 0.18. For the master copy of this documentation see
the Producer Flow Control section in the  <a href="http://qpid.apache.org/documentation.html"
class="external-link" rel="nofollow">Java  documentation</a></td></tr></table></div>

<div>
<ul>
    <li><a href='#UseProducerFlowControl-GeneralInformation'>General Information</a></li>
    <li><a href='#UseProducerFlowControl-Serverconfiguration'>Server configuration</a></li>
<ul>
    <li><a href='#UseProducerFlowControl-ConfiguringaQueuetouseflowcontrol'>Configuring
a Queue to use flow control</a></li>
<ul>
    <li><a href='#UseProducerFlowControl-BrokerLogMessages'>Broker Log Messages</a></li>
</ul>
    <li><a href='#UseProducerFlowControl-Diskquotabasedflowcontrol'>Disk quota-based
flow control</a></li>
<ul>
    <li><a href='#UseProducerFlowControl-BrokerLogMessagesforquotaflowcontrol'>Broker
Log Messages for quota flow control</a></li>
</ul>
</ul>
    <li><a href='#UseProducerFlowControl-Clientimpactandconfiguration'>Client
impact and configuration</a></li>
<ul>
    <li><a href='#UseProducerFlowControl-Usingfailoverwithflowcontrol'>Using failover
with flow control</a></li>
    <li><a href='#UseProducerFlowControl-OlderClients'>Older Clients</a></li>
</ul>
</ul></div>

<h2><a name="UseProducerFlowControl-GeneralInformation"></a>General Information</h2>

<p>The Qpid Java Broker 0.6 release introduces a simplistic producer-side flow control
mechanism into the Java Messaging Broker, causing producers to be flow-controlled when they
attempt to send messages to an overfull queue or overfull message store on a virtual host.</p>

<h2><a name="UseProducerFlowControl-Serverconfiguration"></a>Server configuration</h2>


<h3><a name="UseProducerFlowControl-ConfiguringaQueuetouseflowcontrol"></a>Configuring
a Queue to use flow control</h3>

<p>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 "capacity" of the Queue.  A Queue becomes "underfull"
when its size becomes less than the "flowResumeCapacity".</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;queue&gt;</span>
    <span class="code-tag">&lt;name&gt;</span>test<span class="code-tag">&lt;/name&gt;</span>
    <span class="code-tag">&lt;test&gt;</span>
        <span class="code-tag">&lt;exchange&gt;</span>amq.direct<span
class="code-tag">&lt;/exchange&gt;</span>
        <span class="code-tag">&lt;capacity&gt;</span>10485760<span
class="code-tag">&lt;/capacity&gt;</span>                     <span class="code-tag"><span
class="code-comment">&lt;!-- set the queue capacity to 10Mb --&gt;</span></span>
        <span class="code-tag">&lt;flowResumeCapacity&gt;</span>8388608<span
class="code-tag">&lt;/flowResumeCapacity&gt;</span>  <span class="code-tag"><span
class="code-comment">&lt;!-- set the resume capacity to 8Mb --&gt;</span></span>
    <span class="code-tag">&lt;/test&gt;</span>
<span class="code-tag">&lt;/queue&gt;</span>
</pre>
</div></div>

<p>The default for all queues on a virtual host can also be set</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;virtualhosts&gt;</span>
    <span class="code-tag">&lt;virtualhost&gt;</span>
        <span class="code-tag">&lt;name&gt;</span>localhost<span class="code-tag">&lt;/name&gt;</span>
        <span class="code-tag">&lt;localhost&gt;</span>
            <span class="code-tag">&lt;capacity&gt;</span>10485760<span
class="code-tag">&lt;/capacity&gt;</span>                     <span class="code-tag"><span
class="code-comment">&lt;!-- set the queue capacity to 10Mb --&gt;</span></span>
            <span class="code-tag">&lt;flowResumeCapacity&gt;</span>8388608<span
class="code-tag">&lt;/flowResumeCapacity&gt;</span>  <span class="code-tag"><span
class="code-comment">&lt;!-- set the resume capacity to 8Mb --&gt;</span></span>
        <span class="code-tag">&lt;/localhost&gt;</span>
    <span class="code-tag">&lt;/virtualhost&gt;</span>
<span class="code-tag">&lt;/virtualhosts&gt;</span>
</pre>
</div></div>

<p>Where no flowResumeCapacity is set, the flowResumeCapacity is set to be equal to
the capacity.  Where no capacity is set, capacity is defaulted to 0 meaning there is no capacity
limit.</p>

<h4><a name="UseProducerFlowControl-BrokerLogMessages"></a>Broker Log Messages</h4>

<p>There are four new Broker log messages that may occur if flow control through queue
capacity limits is enabled.</p>

<p>Firstly, when a capacity limited queue becomes overfull, a log message similar to
the following is produced</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
MESSAGE [vh(/test)/qu(MyQueue)] [vh(/test)/qu(MyQueue)] QUE-1003 : Overfull : Size : 1,200
bytes, Capacity : 1,000
</pre>
</div></div>

<p>Then for each channel which becomes blocked upon the overful queue a log message
similar to the following is produced:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
MESSAGE [con:2(guest@anonymous(713889609)/test)/ch:1] [con:2(guest@anonymous(713889609)/test)/ch:1]
CHN-1005 : Flow Control Enforced (Queue MyQueue)
</pre>
</div></div>

<p>When enough messages have been consumed from the queue that it becomes underfull,
then the following log is generated:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
MESSAGE [vh(/test)/qu(MyQueue)] [vh(/test)/qu(MyQueue)] QUE-1004 : Underfull : Size : 600
bytes, Resume Capacity : 800
</pre>
</div></div>

<p>And for every channel which becomes unblocked you will see a message similar to:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
MESSAGE [con:2(guest@anonymous(713889609)/test)/ch:1] [con:2(guest@anonymous(713889609)/test)/ch:1]
CHN-1006 : Flow Control Removed
</pre>
</div></div>

<p>Obviously the details of connection, virtual host, queue, size, capacity, etc would
depend on the configuration in use.</p>

<h3><a name="UseProducerFlowControl-Diskquotabasedflowcontrol"></a>Disk
quota-based flow control</h3>

<p>Since version 0.18 of Qpid Broker, flow control can be triggered when a configured
disk quota is exceeded. This is supported by the BDB and Derby message stores.</p>

<p>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.</p>

<p>Two limits can be configured:</p>
<ol>
	<li>overflow limit - the maximum space on disk (in bytes) which can be used by store.</li>
	<li>underflow limit - when the space on disk drops below this limit, producers are
allowed to resume publishing.</li>
</ol>


<p>An example of quota configuration for the BDB message store is provided below.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
   <span class="code-tag">&lt;store&gt;</span>
       <span class="code-tag">&lt;class&gt;</span>org.apache.qpid.server.store.berkeleydb.BDBMessageStore<span
class="code-tag">&lt;/class&gt;</span>
       <span class="code-tag">&lt;environment-path&gt;</span>${work}/bdbstore/test<span
class="code-tag">&lt;/environment-path&gt;</span>
       <span class="code-tag">&lt;overfull-size&gt;</span>50000000<span
class="code-tag">&lt;/overfull-size&gt;</span>
       <span class="code-tag">&lt;underfull-size&gt;</span>45000000<span
class="code-tag">&lt;/underfull-size&gt;</span>
    <span class="code-tag">&lt;/store&gt;</span>
</pre>
</div></div>

<p>The disk quota functionality is based on "best effort" principle. It means that broker
cannot guarantee that disk space limit will not be exceeded. If several concurrent transactions
are started before the limit is reached then all of them will be committed into disk even
when disk quota is exceeded.</p>

<h4><a name="UseProducerFlowControl-BrokerLogMessagesforquotaflowcontrol"></a>Broker
Log Messages for quota flow control</h4>

<p>There are 2 new Broker log messages that may occur if flow control through disk quota
limits is enabled.<br/>
When virtual host is blocked due to exceeding of the disk quota limit the following message
appears in the broker log</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>[vh(/test)/ms(BDBMessageStore)] MST-1008 : Store overfull, flow control will be
enforced
</pre>
</div></div>

<p>When virtual host is unblocked after cleaning the disk space the following message
appears in the broker log </p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>[vh(/test)/ms(BDBMessageStore)] MST-1009 : Store overfull condition cleared
</pre>
</div></div>



<h2><a name="UseProducerFlowControl-Clientimpactandconfiguration"></a>Client
impact and configuration</h2>

<p>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.</p>

<p>While blocking the client will periodically log the fact that it is blocked waiting
on flow control.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
WARN   AMQSession - Broker enforced flow control has been enforced
WARN   AMQSession - Message send delayed by 5s due to broker enforced flow control
WARN   AMQSession - Message send delayed by 10s due to broker enforced flow control
</pre>
</div></div>

<p>After a set period the send will timeout and throw a JMSException to the calling
code.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
ERROR AMQSession - Message send failed due to timeout waiting on broker enforced flow control
</pre>
</div></div>

<p>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 rollback any transactional work and close the Session.</p>

<p>Both the timeout delay, and the periodicity of the warning messages can be set using
java system properties.  The amount of time (in milliseconds) to wait before timing out is
controlled by the property qpid.flow_control_wait_failure (the default is 120000 - which is
two minutes), 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: the default
value is 5000 milliseconds (i.e. 5 seconds).</p>

<p>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:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
-Dqpid.flow_control_wait_failure=60000
-Dqpid.flow_control_wait_notify_period=10000
</pre>
</div></div>

<h3><a name="UseProducerFlowControl-Usingfailoverwithflowcontrol"></a>Using
failover with flow control</h3>

<p>If flow control feature is used with a failover functionality and connection is lost
when producer is blocked by the flow control, the failover is not started immediately due
to implementation limitation. But it is resumed after the flow control wait interval is expired.
However, failover functionality has 1 minute timeout interval to try to re-establish the connection
and counting of this interval starts after losing of connection. If this timeout is exceeded
the failover will be interrupted and will not be resumed. On other hand, the default flow
control wait interval is set to 2 minutes and as result, the failover can timeout whilst trying
to re-establish the connection for blocked producer(s). </p>

<p>In order to avoid this from happening the failover timeout can be set to the value
bigger than flow control wait interval. For setting of failover timeout the JVM setting "qpid.failover_method_timeout"
can be used as follows</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
-Dqpid.failover_method_timeout=180000
</pre>
</div></div>  

<p>Setting of flow wait interval to the value lower than a failover timeout would allow
failover to restore connectivity.</p>


<h3><a name="UseProducerFlowControl-OlderClients"></a>Older Clients</h3>

<p>This feature was added for the 0.6 releaase of the Java Broker. If an older client
connects to the broker then the flow control commands will be ignored and they will not be
blocked. So to fully benefit from this new feature both Client and Broker need to be at least
version 0.6.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/qpid/Use+Producer+Flow+Control">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=4587720&revisedVersion=12&originalVersion=11">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/qpid/Use+Producer+Flow+Control?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message