diff options
Diffstat (limited to 'doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml')
| -rw-r--r-- | doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml b/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml new file mode 100644 index 0000000000..04212d94ed --- /dev/null +++ b/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml @@ -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> |