QPID-8091: [Broker-J] Update transaction timeout chapter in docbook
[qpid-broker-j.git] / doc / java-broker / src / docbkx / runtime / Java-Broker-Runtime-Transaction-Timeout.xml
1 <?xml version="1.0"?>
2 <!--
4 Licensed to the Apache Software Foundation (ASF) under one
5 or more contributor license agreements. See the NOTICE file
6 distributed with this work for additional information
7 regarding copyright ownership. The ASF licenses this file
8 to you under the Apache License, Version 2.0 (the
9 "License"); you may not use this file except in compliance
10 with the License. You may obtain a copy of the License at
12 http://www.apache.org/licenses/LICENSE-2.0
14 Unless required by applicable law or agreed to in writing,
15 software distributed under the License is distributed on an
17 KIND, either express or implied. See the License for the
18 specific language governing permissions and limitations
19 under the License.
21 -->
23 <section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Java-Broker-Runtime-Transaction-Timeout">
24 <title>Transaction Timeout</title>
25 <section role="h2" xml:id="Java-Broker-Runtime-Transaction-Timeout-GeneralInformation">
26 <title>General Information</title>
27 <para> The transaction timeout mechanism is used to control broker resources when clients
28 using transactions hang, become unresponsive, or simply (due to programming error)
29 begin a transaction and keep using it without ever calling committing or rolling back.</para>
30 <para>Users can choose to configure an idleWarn or openWarn threshold, after which the identified
31 transaction should be logged as a WARN level alert as well as (more importantly) an idleClose or
32 openClose threshold after which the transaction and the connection it applies to will be
33 closed.</para>
34 <para>This feature is particularly useful in environments where the owner of the broker does not
35 have full control over the implementation of clients, such as in a shared services
36 deployment.</para>
37 <para>The following section provide more details on this feature and its use.</para>
38 </section>
39 <section role="h2" xml:id="Java-Broker-Runtime-Transaction-Timeout-Purpose">
40 <title>Purpose</title>
41 <para> This feature has been introduced to address the scenario where an open transaction on the
42 broker holds an open transaction on the persistent store. This can have undesirable consequences
43 if the store does not time out or close long-running transactions, such as with BDB. This can can
44 result in a rapid increase in disk usage size, bounded only by available space, due to growth of
45 the transaction log. </para>
46 </section>
47 <section role="h2" xml:id="Java-Broker-Runtime-Transaction-Timeout-Effect">
48 <title>Effect</title>
49 <para>Full details of configuration options are provided in the sections that follow. This section
50 gives a brief overview of what the Transaction Timeout feature can do.</para>
51 <section role="h3" xml:id="Java-Broker-Runtime-Transaction-Timeout-Effect-Broker-Side">
52 <title>Broker Logging and Connection Close</title>
53 <para>When the openWarn or idleWarn specified threshold is exceeded, the broker will log a WARN
54 level alert with details of the connection on which the threshold has been exceeded,
55 along with the age of the transaction.</para>
56 <para>When the openClose or idleClose specified threshold value is exceeded, the broker will
57 throw an exception back to the client connection via the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/ExceptionListener.html">ExceptionListener</link>, log the
58 action and then close the connection.</para>
59 <para>The example broker log output shown below is where the idleWarn threshold specified is
60 lower than the idleClose threshold and the broker therefore logs the idle transaction 3 times
61 before the close threshold is triggered and the connection closed out.</para>
62 <screen>
63 CON-1011 : Idle Transaction : 13,116 ms
64 CON-1011 : Idle Transaction : 14,116 ms
65 CON-1011 : Idle Transaction : 15,118 ms
66 CON-1002 : Close : Idle transaction timed out
67 </screen>
68 <para>The second example broker log output shown below illustrates the same mechanism operating
69 on an open transaction.</para>
70 <screen>
71 CON-1010 : Open Transaction : 12,406 ms
72 CON-1010 : Open Transaction : 13,406 ms
73 CON-1010 : Open Transaction : 14,406 ms
74 CON-1002 : Close : Open transaction timed out
75 </screen>
76 </section>
77 <section role="h3" xml:id="Java-Broker-Runtime-Transaction-Timeout-Effect-Client-Side">
78 <title>Client Side Effect</title>
79 <para>After a Close threshold has been exceeded, the Broker will close the client's connection.
80 The application must reconnect itself in order to continue work. If the
81 client is a JMS client, the application will be notified by the
82 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJeeDocUrl}javax/jms/ExceptionListener.html">exception
83 listener.</link></para>
84 </section>
85 </section>
86 <section role="h2" xml:id="Java-Broker-Runtime-Transaction-Timeout-Configuration">
87 <title>Configuration</title>
88 <section role="h3" xml:id="Java-Broker-Runtime-Transaction-Timeout-Configuration-Overview">
89 <title>Configuration</title>
90 <para>The transaction timeouts can be specified when a new virtualhost is created or an exiting
91 virtualhost is edited.</para>
92 <para>We would recommend that only warnings are configured at first, which should allow broker
93 administrators to obtain an idea of the distribution of transaction lengths on their systems,
94 and configure production settings appropriately for both warning and closure. Ideally
95 establishing thresholds should be achieved in a representative UAT environment, with clients and
96 broker running, prior to any production deployment.</para>
97 <para>It is impossible to give suggested values, due to the large variation in usage depending on
98 the applications using a broker. However, clearly transactions should not span the expected
99 lifetime of any client application as this would indicate a hung client.</para>
100 <para>When configuring warning and closure timeouts, it should be noted that these only apply to
101 message producers that are connected to the broker, but that a timeout will cause the connection
102 to be closed - this disconnecting all producers and consumers created on that connection.</para>
103 <para>This should not be an issue for environments using Mule or Spring, where connection
104 factories can be configured appropriately to manage a single MessageProducer object per JMS
105 Session and Connection. Clients that use the JMS API directly should be aware that sessions
106 managing both consumers and producers, or multiple producers, will be affected by a single
107 producer hanging or leaving a transaction idle or open, and closed, and must take appropriate
108 action to handle that scenario.</para>
109 </section>
110 </section>
111 </section>