Author: kwall
Date: Sun Nov 25 22:39:16 2012
New Revision: 1413434
URL: http://svn.apache.org/viewvc?rev=1413434&view=rev
Log:
QPID-4471: Add docbook for producer transaction timeout feature of Java Broker.
Added:
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml
Added:
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml?rev=1413434&view=auto
==============================================================================
---
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml
(added)
+++
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml
Sun Nov 25 22:39:16 2012
@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE entities [
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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 id="Java-Broker-Runtime-Producer-Transaction-Timeout">
+ <title>Producer Transaction Timeout</title>
+ <section role="h2"
id="Java-Broker-Runtime-Producer-Transaction-Timeout-GeneralInformation">
+ <title>General Information</title>
+ <para> The transaction timeout mechanism is used to control broker resources
when clients
+ producing messages using transactional sessions hang or otherwise become
unresponsive, or simply
+ begin a transaction and keep using it without ever calling <ulink
+
url="&oracleJeeDocUrl;javax/jms/Session.html#commit">Session#commit()</ulink>.</para>
+ <para>Users can choose to configure an idleWarn or openWarn threshold, after
which the identified
+ transaction should be logged as a WARN level alert as well as (more
importantly) an idleClose or
+ openClose threshold after which the transaction and the connection it
applies to will be
+ closed.</para>
+ <para>This feature is particularly useful in environments where the owner of
the broker does not
+ have full control over the implementation of clients, such as in a shared
services
+ deployment.</para>
+ <para>The following section provide more details on this feature and its
use.</para>
+ </section>
+ <section role="h2"
id="Java-Broker-Runtime-Producer-Transaction-Timeout-Purpose">
+ <title>Purpose</title>
+ <para> This feature has been introduced to address the scenario where an
open transaction on the
+ broker holds an open transaction on the persistent store. This can have
undesirable consequences
+ if the store does not time out or close long-running transactions, such as
with <link
+ linkend="Java-Broker-Stores-BDB-Store">BDB</link>. This can can result in
a rapid increase in
+ disk usage size, bounded only by available space, due to growth of the
transaction log. </para>
+ </section>
+ <section role="h2"
id="Java-Broker-Runtime-Producer-Transaction-Timeout-Scope">
+ <title>Scope</title>
+ <para>Note that only <ulink
url="&oracleJeeDocUrl;javax/jms/MessageProducer.html"
+ >MessageProducer</ulink> clients will be affected by a transaction
timeout, since store
+ transaction lifespan on a consumer only spans the execution of the call to
Session#commit() and
+ there is no scope for a long-lived transaction to arise.</para>
+ <para>It is also important to note that the transaction timeout mechanism is
purely a JMS
+ transaction timeout, and unrelated to any other timeouts in the Qpid client
library and will have
+ no impact on any RDBMS your application may utilise.</para>
+ </section>
+ <section role="h2"
id="Java-Broker-Runtime-Producer-Transaction-Timeout-Effect">
+ <title>Effect</title>
+ <para>Full details of configuration options are provided in the sections
that follow. This section
+ gives a brief overview of what the Transaction Timeout feature can
do.</para>
+ <section role="h3"
id="Java-Broker-Runtime-Producer-Transaction-Timeout-Effect-Broker-Side">
+ <title>Broker Logging and Connection Close</title>
+ <para>When the openWarn or idleWarn specified threshold is exceeded, the
broker will log a WARN
+ level alert with details of the connection and channel on which the
threshold has been exceeded,
+ along with the age of the transaction.</para>
+ <para>When the openClose or idleClose specified threshold value is
exceeded, the broker will
+ throw an exception back to the client connection via the <ulink
+
url="&oracleJeeDocUrl;javax/jms/ExceptionListener.html">ExceptionListener</ulink>,
log the
+ action and then close the connection.</para>
+ <para>The example broker log output shown below is where the idleWarn
threshold specified is
+ lower than the idleClose threshold and the broker therefore logs the idle
transaction 3 times
+ before the close threshold is triggered and the connection closed
out.</para>
+ <screen><![CDATA[CHN-1008 : Idle Transaction : 13,116 ms
+CHN-1008 : Idle Transaction : 14,116 ms
+CHN-1008 : Idle Transaction : 15,118 ms
+CHN-1003 : Close]]>
+ </screen>
+ <para>The second example broker log output shown below illustrates the same
mechanism operating
+ on an open transaction.</para>
+ <screen><![CDATA[
+CHN-1007 : Open Transaction : 12,406 ms
+CHN-1007 : Open Transaction : 13,406 ms
+CHN-1007 : Open Transaction : 14,406 ms
+CHN-1003 : Close]]>
+ </screen>
+ </section>
+ <section role="h3"
id="Java-Broker-Runtime-Producer-Transaction-Timeout-Effect-Client-Side">
+ <title>Client Side Effect</title>
+ <para>After a Close threshold has been exceeded, the trigger client will
receive this exception
+ on its <ulink
url="&oracleJeeDocUrl;javax/jms/ExceptionListener.html">exception
+ listener</ulink>, prior to being disconnected:</para>
+ <computeroutput>org.apache.qpid.AMQConnectionClosedException: Error: Idle
transaction timed out
+ [error code 506: resource error]</computeroutput>
+ <para>Any later attempt to use the connection will result in this exception
being thrown:</para>
+ <screen><![CDATA[Producer: Caught an Exception:
javax.jms.IllegalStateException: Object
org.apache.qpid.client.AMQSession_0_8@129b0e1 has been closed
+ javax.jms.IllegalStateException: Object
org.apache.qpid.client.AMQSession_0_8@129b0e1 has been closed
+ at org.apache.qpid.client.Closeable.checkNotClosed(Closeable.java:70)
+ at org.apache.qpid.client.AMQSession.checkNotClosed(AMQSession.java:555)
+ at
org.apache.qpid.client.AMQSession.createBytesMessage(AMQSession.java:573)]]>
+ </screen>
+ <para>Thus clients must be able to handle this case successfully,
reconnecting where required and
+ registering an exception listener on all connections. This is critical,
and must be communicated
+ to client applications by any broker owner switching on transaction
timeouts.</para>
+ </section>
+
+ </section>
+ <section role="h2"
id="Java-Broker-Runtime-Producer-Transaction-Timeout-Configuration">
+ <title>Configuration</title>
+ <section role="h3"
id="Java-Broker-Runtime-Producer-Transaction-Timeout-Configuration-Overview">
+ <title>Configuration</title>
+ <para>Transaction timeouts are configurable separately on each defined
virtual host, using the
+ virtualhosts.xml file.</para>
+ <para>We would recommend that only warnings are configured at first, which
should allow broker
+ administrators to obtain an idea of the distribution of transaction
lengths on their systems,
+ and configure production settings appropriately for both warning and
closure. Ideally
+ establishing thresholds should be achieved in a representative UAT
environment, with clients and
+ broker running, prior to any production deployment.</para>
+ <para>It is impossible to give suggested values, due to the large variation
in usage depending on
+ the applications using a broker. However, clearly transactions should not
span the expected
+ lifetime of any client application as this would indicate a hung
client.</para>
+ <para>When configuring warning and closure timeouts, it should be noted
that these only apply to
+ message producers that are connected to the broker, but that a timeout
will cause the connection
+ to be closed - this disconnecting all producers and consumers created on
that connection.</para>
+ <para>This should not be an issue for environments using Mule or Spring,
where connection
+ factories can be configured appropriately to manage a single
MessageProducer object per JMS
+ Session and Connection. Clients that use the JMS API directly should be
aware that sessions
+ managing both consumers and producers, or multiple producers, will be
affected by a single
+ producer hanging or leaving a transaction idle or open, and closed, and
must take appropriate
+ action to handle that scenario.</para>
+ </section>
+ <section role="h3"
+
id="Java-Broker-Runtime-Producer-Transaction-Timeout-Configuration-Virtualhosts">
+ <title>Virtualhosts.xml</title>
+ <para> The JMS transaction timeouts are configured on each virtual host
defined in the XML
+ configuration files.</para>
+ <para> The default values for each of the parameters is 0, indicating that
the particular check
+ is disabled.</para>
+ <para> Any or all of the parameters can be set, using the desired value in
milliseconds, and will
+ be checked each time the housekeeping process runs, usually set to run
every 30 seconds in
+ standard configuration. The meaning of each property is as follows:</para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>openWarn - the time a transaction can be open for (with activity
occurring on it) after
+ which a warning alert will be issued.</para>
+ </listitem>
+ <listitem>
+ <para>openClose - the time a transaction can be open for before the
connection it is on is
+ closed.</para>
+ </listitem>
+ <listitem>
+ <para>idleWarn - the time a transaction can be idle for (with no
activity occurring on it)
+ after which a warning alert will be issued.</para>
+ </listitem>
+ <listitem>
+ <para>idleClose - the time a transaction can be idle for before the
connection it is on is
+ closed.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para> The virtualhosts configuration is shown below, and must occur inside
the
+ //virtualhosts/virtualhost/name/ elements: </para>
+ <example>
+<title>Configuring producer transaction timeout</title>
+ <programlisting><![CDATA[
+<transactionTimeout>
+ <openWarn>10000</openWarn>
+ <openClose>20000</openClose>
+ <idleWarn>5000</idleWarn>
+ <idleClose>15000</idleClose>
+</transactionTimeout>
+ ]]></programlisting>
+ </example>
+ </section>
+ </section>
+</section>
Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml?rev=1413434&r1=1413433&r2=1413434&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml Sun Nov 25
22:39:16 2012
@@ -25,4 +25,5 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
href="Java-Broker-Runtime-Log-Files.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
href="Java-Broker-Runtime-Alerts.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
href="Java-Broker-Runtime-Disk-Space-Management.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
href="Java-Broker-Runtime-Producer-Transaction-Timeout.xml"/>
</chapter>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
