diff options
| author | Andrew Donald Kennedy <grkvlt@apache.org> | 2010-12-07 02:16:22 +0000 |
|---|---|---|
| committer | Andrew Donald Kennedy <grkvlt@apache.org> | 2010-12-07 02:16:22 +0000 |
| commit | 73140680684872939df955e36f3f2ec2b134dd7e (patch) | |
| tree | 7105303d07423173d14bf6610fb795ceeefaf626 /qpid/doc | |
| parent | dbbd5f5f42a32d084e8dfc82806fd3e29dd9a143 (diff) | |
| download | qpid-python-73140680684872939df955e36f3f2ec2b134dd7e.tar.gz | |
QPID-2680: Tidied up docbook formatting
git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1042890 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'qpid/doc')
| -rw-r--r-- | qpid/doc/book/src/How-to-Use-SlowConsumerDisconnect.xml | 372 |
1 files changed, 91 insertions, 281 deletions
diff --git a/qpid/doc/book/src/How-to-Use-SlowConsumerDisconnect.xml b/qpid/doc/book/src/How-to-Use-SlowConsumerDisconnect.xml index 4d5bad73a3..5f4c627430 100644 --- a/qpid/doc/book/src/How-to-Use-SlowConsumerDisconnect.xml +++ b/qpid/doc/book/src/How-to-Use-SlowConsumerDisconnect.xml @@ -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> - - <para> <delay>60<delay/> </para> - - <para> <timeunit>seconds<timeunit/> </para> - - <para> <slow-consumer-detection/> </para> - - <para> </test> </para> - - <para> </virtualhost> </para> - - <para> + along with the unit of time used to specify that frequency. </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_0_8@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_0_8@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_0_8@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_0_8@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 /[apache.qpid.client.AMQSession/] Closing sess 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 /[apache.qpid.client.AMQSession/] Closing sess <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 /[apache.qpid.client.AMQSession/] Closing sess 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 /[apache.qpid.client.AMQSession/] Closing sess <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 /[apache.qpid.client.AMQSession/] Closing sess <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 /[apache.qpid.client.AMQSession/] Closing sess 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 configure SCD: <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 configure SCD: 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> - |