1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
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>
|
