| <?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> |