Author: grkvlt
Date: Tue Dec 7 02:16:22 2010
New Revision: 1042890
URL: http://svn.apache.org/viewvc?rev=1042890&view=rev
Log:
QPID-2680: Tidied up docbook formatting
Modified:
qpid/trunk/qpid/doc/book/src/How-to-Use-SlowConsumerDisconnect.xml
Modified: qpid/trunk/qpid/doc/book/src/How-to-Use-SlowConsumerDisconnect.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/How-to-Use-SlowConsumerDisconnect.xml?rev=1042890&r1=1042889&r2=1042890&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/How-to-Use-SlowConsumerDisconnect.xml
(original)
+++ qpid/trunk/qpid/doc/book/src/How-to-Use-SlowConsumerDisconnect.xml Tue Dec
7 02:16:22 2010
@@ -26,143 +26,75 @@
<section>
<title>Introduction</title>
- <para>
-
- </para>
-
<para>Slow Consumer Disconnect (SCD) is a new feature in Qpid that provides
a configurable
mechanism to prevent a single slow consumer from causing a back up of
unconsumed messages on
the broker. </para>
- <para>
-
- </para>
-
<para>This is most relevant where Topics are in use, since a published
message is not removed
from the broker's memory until all subscribers have acknowledged that
message. </para>
- <para>
-
- </para>
-
<para>Cases where a consumer is 'slow' can arise due to one of the
following: poor network
- connectivity exists; a transitory system issue affects a single
client;a single subscriber
+ connectivity exists; a transient system issue affects a single client;
a single subscriber
written by a client team is behaving incorrectly and not acknowledging
messages; a
downstream resource such as a database is non-responsive. </para>
- <para>
-
- </para>
-
<para>SCD will enable the application owner to configure limits for a given
consumer's queue and
the behaviour to execute when those limits are reached. </para>
- <para>
-
- </para>
-
</section>
<section>
<title>What can it do?</title>
- <para>
-
- </para>
-
- <para>SCD is only applicable to topics and durable subscriptions and can be
configured on either
- topic or a subscription name. </para>
-
- <para>
-
- </para>
+ <para>SCD is only applicable to topics or durable subscriptions and can be
configured on either
+ a topic or a subscription name. </para>
<para>On triggering of a specified threshold the offending client will be
disconnected from the
broker with a 506 error code wrapped in a JMSException returned to the
client via the
ExceptionListener registered on the Connection object. </para>
- <para>Note that it is essential that an ExceptionListener be specified
by the client on
+
+ <para>Note that it is essential that an ExceptionListener be specified by
the client on
creation of the connection and that exceptions coming back on that
listener are handled
correctly. </para>
- <para>
-
- </para>
-
</section>
<section>
<title>Frequency of SCD Checking</title>
- <para>
-
- </para>
-
<section>
<title><emphasis role='bold'>Configuring Frequency</emphasis></title>
- <para>
-
- </para>
-
<para>You can configure the frequency with which the SCD process will
check for slow consumers,
- along with the unit of time you're using to specify that frequency.
</para>
-
- <para>
-
- </para>
-
- <para><emphasis
role="italic">virtualhosts.virtualhost.slow-consumer-detection. delay</emphasis>
- and <emphasis role="italic">.timeunit</emphasis> are the elements
used to specify the
- frequency and timeunit for that frequency on the virtualhosts.xml
file e.g. </para>
-
- <para> </para>
-
- <para> <virtualhosts></para>
-
- <para> <default>test</default> </para>
-
- <para> <virtualhost> </para>
-
- <para> <name>test</name> </para>
-
- <para> <test> </para>
-
- <para> <slow-consumer-detection> </para>
+ along with the unit of time used to specify that frequency. </para>
- <para> <delay>60<delay/> </para>
-
- <para> <timeunit>seconds<timeunit/> </para>
-
- <para> <slow-consumer-detection/> </para>
-
- <para> </test> </para>
-
- <para> </virtualhost> </para>
-
- <para>
+ <para>The <emphasis
role="italic">virtualhosts.virtualhost.hostname.slow-consumer-detection</emphasis>
+ elements <emphasis role="italic">delay</emphasis> and <emphasis
role="italic">timeunit</emphasis>
+ are used to specify the frequency and timeunit respectively in the
virtualhosts.xml
+ file e.g. </para>
+
+<programlisting>
+<virtualhosts>
+ <default>test</default>
+ <virtualhost>
+ <name>test</name>
+ <test>
+ <slow-consumer-detection>
+ <delay>60<delay/>
+ <timeunit>seconds<timeunit/>
+ <slow-consumer-detection/>
+ </test>
+ </virtualhost>
</virtualhosts>
- </para>
-
- <para>
-
- </para>
+</programlisting>
</section>
<section>
<title><emphasis role='bold'>SCD Log output</emphasis></title>
- <para>
-
- </para>
-
- <para>
-When the SCD component finds a queue with a configured threshold to check, the
operational logging component (if enabled) will log:
- </para>
+ <para>When the SCD component finds a queue with a configured threshold to
check, the operational
+ logging component (if enabled) will output the following line:</para>
- <para>
-SCD-1003 : Checking Status of Queue
- </para>
-
- <para>
-
- </para>
+ <programlisting>
+ SCD-1003 : Checking Status of Queue
+ </programlisting>
</section>
@@ -173,112 +105,38 @@ SCD-1003 : Checking Status of Queue
<para>When a Slow Consumer is disconnected, the client receives a 506 error
from the broker
wrapped in a JMSException and the Session and Connection are
closed:</para>
- <para> </para>
-
- <para>
-Dispatcher-Channel-1 2010-09-01 16:23:34,206 INFO
[qpid.client.AMQSession.Dispatcher] Dispatcher-Channel-1 thread terminating for
channel 1:org.apache.qpid.client.amqsession_...@1de8aa8
- </para>
-
- <para>
+<programlisting>
+Dispatcher-Channel-1 2010-09-01 16:23:34,206 INFO
[qpid.client.AMQSession.Dispatcher]
+ Dispatcher-Channel-1 thread terminating for channel
1:org.apache.qpid.client.amqsession_...@1de8aa8
pool-2-thread-3 2010-09-01 16:23:34,238 INFO
[apache.qpid.client.AMQConnection] Closing AMQConnection due to
- </para>
-
- <para>
-:org.apache.qpid.AMQChannelClosedException: Error: Consuming to slow. /[error
code 506: resource error/]
- </para>
-
- <para>
+ :org.apache.qpid.AMQChannelClosedException: Error: Consuming to slow.
[error code 506: resource error]
javax.jms.JMSException: 506
- </para>
-
- <para>
- at
org.apache.qpid.client.AMQConnection.exceptionReceived(AMQConnection.java:1396)
- </para>
-
- <para>
- at
org.apache.qpid.client.protocol.AMQProtocolHandler.exception(AMQProtocolHandler.java:329)
- </para>
-
- <para>
- at
org.apache.qpid.client.protocol.AMQProtocolHandler.methodBodyReceived(AMQProtocolHandler.java:536)
- </para>
-
- <para>
- at
org.apache.qpid.client.protocol.AMQProtocolSession.methodFrameReceived(AMQProtocolSession.java:453)
- </para>
-
- <para>
- at org.apache.qpid.framing.AMQMethodBodyImpl.handle(AMQMethodBodyImpl.java:93)
- </para>
-
- <para>
- at
org.apache.qpid.client.protocol.AMQProtocolHandler$1.run(AMQProtocolHandler.java:462)
- </para>
-
- <para>
- at org.apache.qpid.pool.Job.processAll(Job.java:110)
- </para>
-
- <para>
- at org.apache.qpid.pool.Job.run(Job.java:149)
- </para>
-
- <para>
- at
java.util.concurrent.ThreadPoolExecutor$Worker.runTask(ThreadPoolExecutor.java:885)
- </para>
-
- <para>
- at
java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:907)
- </para>
-
- <para>
- at java.lang.Thread.run(Thread.java:619)
- </para>
-
- <para>
-Caused by: org.apache.qpid.AMQChannelClosedException: Error: Consuming to
slow. /[error code 506: resource error/]
- </para>
-
- <para>
- at
org.apache.qpid.client.handler.ChannelCloseMethodHandler.methodReceived(ChannelCloseMethodHandler.java:96)
- </para>
-
- <para>
- at
org.apache.qpid.client.handler.ClientMethodDispatcherImpl.dispatchChannelClose(ClientMethodDispatcherImpl.java:163)
- </para>
-
- <para>
- at
org.apache.qpid.framing.amqp_8_0.ChannelCloseBodyImpl.execute(ChannelCloseBodyImpl.java:140)
- </para>
-
- <para>
- at
org.apache.qpid.client.state.AMQStateManager.methodReceived(AMQStateManager.java:112)
- </para>
-
- <para>
- at
org.apache.qpid.client.protocol.AMQProtocolHandler.methodBodyReceived(AMQProtocolHandler.java:511)
- </para>
-
- <para>
- ... 8 more
- </para>
-
- <para>
-main 2010-09-01 16:23:34,316 INFO /[apache.qpid.client.AMQSession/] Closing
session: org.apache.qpid.client.amqsession_...@ffeef1
- </para>
-
- <para>
-
- </para>
+at
org.apache.qpid.client.AMQConnection.exceptionReceived(AMQConnection.java:1396)
+at
org.apache.qpid.client.protocol.AMQProtocolHandler.exception(AMQProtocolHandler.java:329)
+at
org.apache.qpid.client.protocol.AMQProtocolHandler.methodBodyReceived(AMQProtocolHandler.java:536)
+at
org.apache.qpid.client.protocol.AMQProtocolSession.methodFrameReceived(AMQProtocolSession.java:453)
+at org.apache.qpid.framing.AMQMethodBodyImpl.handle(AMQMethodBodyImpl.java:93)
+at
org.apache.qpid.client.protocol.AMQProtocolHandler$1.run(AMQProtocolHandler.java:462)
+at org.apache.qpid.pool.Job.processAll(Job.java:110)
+at org.apache.qpid.pool.Job.run(Job.java:149)
+at
java.util.concurrent.ThreadPoolExecutor$Worker.runTask(ThreadPoolExecutor.java:885)
+at
java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:907)
+at java.lang.Thread.run(Thread.java:619)
+Caused by: org.apache.qpid.AMQChannelClosedException: Error: Consuming to
slow. [error code 506: resource error]
+at
org.apache.qpid.client.handler.ChannelCloseMethodHandler.methodReceived(ChannelCloseMethodHandler.java:96)
+at
org.apache.qpid.client.handler.ClientMethodDispatcherImpl.dispatchChannelClose(ClientMethodDispatcherImpl.java:163)
+at
org.apache.qpid.framing.amqp_8_0.ChannelCloseBodyImpl.execute(ChannelCloseBodyImpl.java:140)
+at
org.apache.qpid.client.state.AMQStateManager.methodReceived(AMQStateManager.java:112)
+at
org.apache.qpid.client.protocol.AMQProtocolHandler.methodBodyReceived(AMQProtocolHandler.java:511)
+... 8 more
+main 2010-09-01 16:23:34,316 INFO [apache.qpid.client.AMQSession] Closing
session:
+ org.apache.qpid.client.amqsession_...@ffeef1
+</programlisting>
</section>
<section>
<title>Disconnection Thresholds</title>
- <para>
-
- </para>
-
<section>
<title>Topic Subscriptions</title>
<para>One key feature of SCD is the disconnection of a consuming client
when a specified
@@ -286,10 +144,6 @@ main 2010-09-01 16:23:34,316 INFO /[apac
longer be delivered to the private queue which was associated with
that consuming client,
thus reducing any associated backlog in the broker. </para>
- <para>
-
- </para>
-
</section>
<section>
@@ -304,10 +158,6 @@ main 2010-09-01 16:23:34,316 INFO /[apac
<para>Full details of how to configure the thresholds are provided below.
</para>
- <para>
-
- </para>
-
</section>
<section>
@@ -324,10 +174,6 @@ main 2010-09-01 16:23:34,316 INFO /[apac
by a queue depth greater than the threshold specified i.e. when a
broker receives a
message that takes the queue depth over the threshold. </para>
- <para>
-
- </para>
-
</section>
<section>
@@ -335,10 +181,6 @@ main 2010-09-01 16:23:34,316 INFO /[apac
<para>You can use the message count for the consumer's queue as the
trigger, where a count
higher than that specified will trigger disconnection. </para>
- <para>
-
- </para>
-
</section>
<section>
@@ -350,8 +192,8 @@ main 2010-09-01 16:23:34,316 INFO /[apac
<emphasis role='bold'>Delete Temporary Queues Only</emphasis>
</para>
- <para>If you do not specify a topicDelete element in your configuration,
then only temporary
- queues associated with a topic subscription will be delete on client
disconnect. This is
+ <para>If you do not specify a <topicDelete/> element in your
configuration, then only temporary
+ queues associated with a topic subscription will be deleted on
client disconnect. This is
the default behaviour. </para>
<para/>
@@ -376,21 +218,20 @@ main 2010-09-01 16:23:34,316 INFO /[apac
The following steps are required to configure SCD:
</para>
- <para>
-- enable SCD checking for your virtual host
- </para>
-
- <para>
-- specify frequency for SCD checking
- </para>
-
- <para>
-- define thresholds for the topic
- </para>
-
- <para>
-- define the policy to apply on trigger
- </para>
+<itemizedlist>
+ <listitem>
+ <para>Enable SCD checking for your virtual host</para>
+ </listitem>
+ <listitem>
+ <para>Specify frequency for SCD checking</para>
+ </listitem>
+ <listitem>
+ <para>Define thresholds for the topic</para>
+ </listitem>
+ <listitem>
+ <para>Define the policy to apply on trigger </para>
+ </listitem>
+</itemizedlist>
<para>The example below shows a simple definition, with all three
thresholds specified and a
simple disconnection, with deletion of any temporary queue, defined.
</para>
@@ -398,36 +239,26 @@ The following steps are required to conf
<para>For a durable subscription to this topic, no queue deletion would be
applied on disconnect
- which is likely to be undesirable (see section above). </para>
- <para><topics> </para>
-
- <para> <topic> </para>
-
- <para> <name>stocks.us.*</name> </para>
-
- <para> <slow-consumer-detection> </para>
-
- <para> <!-- The maximum depth before which the policy will be
applied--> </para>
-
- <para> <depth>4235264</depth> </para>
-
- <para> <!-- The maximum message age before which the policy
will be applied--> </para>
-
- <para> <messageAge>600000</messageAge> </para>
-
- <para> <!-- The maximum number of message before which the
policy will be
- applied--> </para>
-
- <para> <messageCount>50</messageCount> </para>
-
- <para> <!-- Policy Selection --> </para>
-
- <para> <policy name="TopicDelete"/> </para>
-
- <para> </slow-consumer-detection> </para>
-
- <para> </topic> </para>
-
- <para></topics> </para>
+<programlisting>
+<topics>
+ <topic>
+ <name>stocks.us.*</name>
+ <slow-consumer-detection>
+ <!-- The maximum depth before which -->
+ <!-- the policy will be applied-->
+ <depth>4235264</depth>
+ <!-- The maximum message age before which -->
+ <!-- the policy will be applied-->
+ <messageAge>600000</messageAge>
+ <!-- The maximum number of message before -->
+ <!-- which the policy will be applied-->
+ <messageCount>50</messageCount>
+ <!-- Policy Selection -->
+ <policy name="TopicDelete"/>
+ </slow-consumer-detection>
+ </topic>
+</topics>
+</programlisting>
</section>
@@ -439,32 +270,11 @@ The following steps are required to conf
disconnected with a 506 error code, to avoid them getting into a
thrashing state where they
continually attempt to connect, fail to consume fast enough and are
disconnected again. </para>
- <para>
-
- </para>
-
<para>Clients affected by slow consumer disconnect configuration should
always use transactions
where duplicate processing of an incoming message would have adverse
affects, since they may
receive a message more than once if disconnected before acknowledging
a message in flight. </para>
- <para>
-
- </para>
-
- <para>
-
- </para>
-
- <para>
-
- </para>
-
- <para>
-
- </para>
-
</section>
</section>
-
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
