rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/timeouts.html

   1 <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>The Apache Tomcat Connector - Generic HowTo - Timeouts HowTo</title><meta name="author" value="Rainer Jung"><meta name="email" value="rjung@apache.org"><link href="../../style.css" type="text/css" rel="stylesheet"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="4"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a href="http://tomcat.apache.org/"><img src="../../images/tomcat.gif" align="left" alt="Apache Tomcat" border="0"></a><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="http://www.apache.org/images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top"><h1>The Apache Tomcat Connector - Generic HowTo</h1><h2>Timeouts HowTo</h2></td><td align="right" valign="top" nowrap="true"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
   2 <br>
   3 <p>Setting communication timeouts is very important to improve the
   4 communication process. They help to detect problems and stabilise
   5 a distributed system. JK can use several different timeout types, which
   6 can be individually configured. For historical reasons, all of them are
   7 disabled by default. This HowTo explains their use and gives
   8 hints how to find appropriate values.
   9 </p>
  10 <p>All timeouts can be configured in the workers.properties file.
  11 For a complete reference of all worker configuration
  12 items, please consult the worker <a href="../../reference/workers.html">reference</a>.
  13 This page assumes, that you are using at least version 1.2.16 of JK.
  14 Dependencies on newer versions will be mentioned where necessary.
  15 </p>
  16 <p><font color="#ff0000">
  17 Do not set timeouts to extreme values. Very small timeouts will likely
  18 be counterproductive.
  19 </font></p>
  20 <p><font color="#ff0000">
  21 Long Garbage Collection pauses on the backend do not make a good
  22 fit with some timeouts. Try to optimise your Java memory and GC settings.
  23 </font></p>
  24 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JK Timeout Attributes"><strong>JK Timeout Attributes</strong></a></font></td></tr><tr><td><blockquote>
  25 <br>
  26 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="CPing/CPong"><strong>CPing/CPong</strong></a></font></td></tr><tr><td><blockquote>
  27 <p>
  28 CPing/CPong is our notion for using small test packets to check the
  29 status of backend connections. JK can use such test packets directly after establishing
  30 a new backend connection (connect mode) and also directly before each request gets
  31 send to a backend (prepost mode).
  32 Starting with version 1.2.27 it can also be used when a connection was idle
  33 for a long time (interval mode).
  34 The maximum waiting time (timeout) for a CPong answer to a CPing and the idle
  35 time in interval mode can be configured.
  36 </p>
  37 <p>
  38 The test packets will be answered by the backend very fast with a minimal amount of
  39 needed processing resources. A positive answer tells us, that the backend can be reached
  40 and is actively processing requests. It does not detect, if some context is deployed
  41 and working. The benefit of CPing/CPong is a fast detection of a communication
  42 problem with the backend. The downside is a slightly increased latency.
  43 </p>
  44 <p>
  45 The worker attribute <b>ping_mode</b> can be set to a combination of characters
  46 to determine, in which situations test packets are used:
  47 <ul>
  48 <li><b>C</b>: connect mode, timeout <b>ping_timeout</b> overwritten by <b>connect_timeout</b></li>
  49 <li><b>P</b>: prepost mode, timeout <b>ping_timeout</b> overwritten by <b>prepost_timeout</b></li>
  50 <li><b>I</b>: interval mode, timeout <b>ping_timeout</b>, idle time <b>connection_ping_interval</b></li>
  51 <li><b>A</b>: all modes</li>
  52 </ul>
  53 </p>
  54 <p>
  55 Multiple values must be concatenated without any separator characters.
  56 We recommend using all CPing tests. If your application is very latency sensitive, then
  57 you should only use the combination of connect and interval mode.
  58 </p>
  59 <p>
  60 Activating the CPing probing via <b>ping_mode</b> has been added in version 1.2.27.
  61 For older versions only the connect and prepost modes exist and must be activated by
  62 explicitely setting <b>connect_timeout</b> and <b>prepost_timeout</b>.
  63 </p>
  64 <p>
  65 The worker attribute <b>ping_timeout</b> sets the default wait timeout
  66 in milliseconds for CPong for all modes. By default the value is "10000"
  67 milliseconds. The value only gets used, if you activate CPing/Cpong probes
  68 via <b>ping_mode</b>. The default value should be fine, except if you experience
  69 very long Java garbage collection pauses.
  70 Depending on your network latency and stability, good custom values
  71 often are between 5000 and 15000 milliseconds.
  72 You can overwrite the timeout used for connect and prepost mode with
  73 <b>connect_timeout</b> and <b>prepost_timeout</b>.
  74 Remember: don't use extremely small values.
  75 </p>
  76 <p>
  77 The worker attribute <b>connect_timeout</b> sets the wait timeout
  78 in milliseconds for CPong during connection establishment. You can use it
  79 if you want to overwrite the general timeout set with <b>ping_timeout</b>.
  80 To use connect mode CPing, you need to enable it via <b>ping_mode</b>.
  81 Since JK usually uses persistent connections, opening new connections is a
  82 rare event. We therefore recommend activating connect mode.
  83 Depending on your network latency and stability, good values often
  84 are between 5000 and 15000 milliseconds.
  85 Remember: don't use extremely small values.
  86 </p>
  87 <p>
  88 The worker attribute <b>prepost_timeout</b> sets the wait timeout
  89 in milliseconds for CPong before request forwarding. You can use it
  90 if you want to overwrite the general timeout set with <b>ping_timeout</b>.
  91 To use prepost mode CPing, you need to enable it via <b>ping_mode</b>.
  92 Activating this type of CPing/CPong adds a small latency to each
  93 request. Usually this is small enough and the benefit of CPing/CPong is more important.
  94 So in general we also recommend using <b>prepost_timeout</b>.
  95 Depending on your network latency and stability, good values often
  96 are between 5000 and 10000 milliseconds.
  97 Remember: don't use extremely small values.
  98 </p>
  99 <p>
 100 Until version 1.2.27 <b>ping_mode</b> and <b>ping_timeout</b> did not
 101 exist and to enable connect or prepost mode CPing you had to set <b>connect_timeout</b>
 102 respectively <b>prepost_timeout</b> to some reasonable positive value.
 103 </p>
 104 </blockquote></td></tr></table>
 105
 106 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Low-Level TCP Timeouts"><strong>Low-Level TCP Timeouts</strong></a></font></td></tr><tr><td><blockquote>
 107 <p>
 108 Some platforms allow to set timeouts for all operations on TCP sockets.
 109 This is available for Linux and Windows, other platforms do not support this,
 110 e.g. Solaris. If your platform supports TCP send and receive timeouts,
 111 you can set them using the worker attribute <b>socket_timeout</b>.
 112 You can not set the two timeouts to different values.
 113 </p>
 114 <p>
 115 JK will accept this attribute even if your platform does not support
 116 socket timeouts. In this case setting the attribute will have no effect.
 117 By default the value is "0" and the timeout is disabled.
 118 You can set the attribute to some seconds value (not: milliseconds).
 119 JK will then set the send and the receive timeouts of the backend
 120 connections to this value. The timeout is low-level, it is
 121 used for each read and write operation on the socket individually.
 122 </p>
 123 <p>
 124 Using this attribute will make JK react faster to some types of network problems.
 125 Unfortunately socket timeouts have negative side effects, because for most
 126 platforms, there is no good way to recover from such a timeout, once it fired.
 127 For JK there is no way to decide, if this timeout fired because of real network
 128 problems, or only because it didn't receive an answer packet from a backend in time.
 129 So remember: don't use extremely small values.
 130 </p>
 131 <p>
 132 For the general case of connection establishment you can use
 133 <b>socket_connect_timeout</b>. It takes a millisecond value and works
 134 on most platforms, even if <b>socket_timeout</b> is not supported.
 135 We recommend using <b>socket_connect_timeout</b> because in some network
 136 failure situations failure detection during connection establishment
 137 can take several minutes due to TCP retransmits. Depending on the quality
 138 of your network a timeout somewhere between 1000 and 5000 milliseconds
 139 should be fine. Note that <b class="code">socket_timeout</b> is in seconds, and
 140 <b class="code">socket_connect_timeout</b> in milliseconds.
 141 </p>
 142 </blockquote></td></tr></table>
 143
 144 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Connection Pools and Idle Timeouts"><strong>Connection Pools and Idle Timeouts</strong></a></font></td></tr><tr><td><blockquote>
 145 <p>
 146 JK handles backend connections in a connection pool per web server process.
 147 The connections are used in a persistent mode. After a request completed
 148 successfully we keep the connection open and wait for the next
 149 request to forward. The connection pool is able to grow according
 150 to the number of threads that want to forward requests in parallel.
 151 </p>
 152 <p>
 153 Most applications have a varying load depending on the hour of the day
 154 or the day of the month. Other reasons for a growing connection pool
 155 would be temporary slowness of backends, leading to an increasing
 156 congestion of the frontends like web servers. Many backends use a dedicated
 157 thread for each incoming connection they handle. So usually one wants the
 158 connection pool to shrink, if the load diminishes.
 159 </p>
 160 <p>
 161 JK allows connections in the pool to get closed after some idle time.
 162 This maximum idle time can be configured with the attribute
 163 <b>connection_pool_timeout</b> which is given in units of seconds.
 164 The default value is "0", which disables closing idle connections.
 165 </p>
 166 <p>
 167 We generally recommend values around 10 minutes, so setting
 168 <b>connection_pool_timeout</b> to 600 (seconds). If you use this attribute,
 169 please also set the attribute <b>connectionTimeout</b> in the AJP
 170 Connector element of your Tomcat server.xml configuration file to
 171 an analogous value. <b>Caution</b>: connectionTimeout is in milliseconds.
 172 So if you set JK connection_pool_timeout to 600, you should set Tomcat
 173 connectionTimeout to 600000.
 174 </p>
 175 <p>
 176 JK connections do not get closed immediately after the timeout passed.
 177 Instead there is an automatic internal maintenance task
 178 running every 60 seconds, that checks the idle status of all connections.
 179 The 60 seconds interval
 180 can be adjusted with the global attribute worker.maintain. We do not
 181 recommend to change this value, because it has a lot of side effects.
 182 Until version 1.2.26, the maintenance task only runs, if requests get
 183 processed. So if your web server has processes that do not receive any
 184 requests for a long time, there is no way to close the idle connections
 185 in its pool. Starting with version 1.2.27 you can configure an independent
 186 watchdog thread when using Apache 2.x with threaded APR or IIS.
 187 </p>
 188 <p>
 189 The maximum connection pool size can be configured with the
 190 attribute <b>connection_pool_size</b>. We generally do not recommend
 191 to use this attribute in combination with Apache httpd. For
 192 Apache httpd we automatically detect the number of threads per
 193 process and set the maximum pool size to this value. For IIS we use
 194 a default value of 250 (before version 1.2.20: 10),
 195 for the Sun Web Server the default is "1".
 196 We strongly recommend adjusting this value for IIS and the Sun Web Server
 197 to the number of requests one web server process should
 198 be able to send to a backend in parallel. You should measure how many connections
 199 you need during peak hours without performance problems, and then add some
 200 percentage depending on your growth rate etc. Finally you should check,
 201 whether your web server processes are able to use at least as many threads,
 202 as you configured as the pool size.
 203 </p>
 204 <p>
 205 The JK attribute <b>connection_pool_minsize</b> defines,
 206 how many idle connections remain when the pool gets shrunken.
 207 By default this is half of the maximum pool size.
 208 </p>
 209 </blockquote></td></tr></table>
 210
 211 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Firewall Connection Dropping"><strong>Firewall Connection Dropping</strong></a></font></td></tr><tr><td><blockquote>
 212 <p>
 213 One particular problem with idle connections comes from firewalls, that
 214 are often deployed between the web server layer and the backend.
 215 Depending on their configuration, they will silently drop
 216 connections from their status table if they are idle for to long.
 217 </p>
 218 <p>
 219 From the point of view of JK and of the web server, the other side
 220 simply doesn't answer any traffic. Since TCP is a reliable protocol
 221 it detects the missing TCP ACKs and tries to resend the packets for
 222 a relatively long time, typically several minutes.
 223 </p>
 224 <p>
 225 Many firewalls will allow connection closing, even if they dropped
 226 the connection for normal traffic. Therefore you should always use
 227 <a href="#Connection Pools and Idle Timeouts">connection_pool_timeout and
 228 connection_pool_minsize</a> on the JK side
 229 and connectionTimeout on the Tomcat side.
 230 </p>
 231 <p>
 232 Furthermore using the boolean attribute <b>socket_keepalive</b> you can
 233 set a standard socket option, that automatically sends TCP keepalive packets
 234 after some idle time on each connection. By default this is set to "False".
 235 If you suspect idle connection drops by firewalls you should set this to
 236 "True".
 237 </p>
 238 <p>
 239 Unfortunately the default intervals and algorithms for these packets
 240 are platform specific. You might need to inspect TCP tuning options for
 241 your platform on how to control TCP keepalive.
 242 Often the default intervals are much longer than the firewall timeouts
 243 for idle connections. Nevertheless we recommend talking to your firewall
 244 administration and your platform administration in order to make them agree
 245 on good configuration values for the firewall and the platform TCP tuning.
 246 </p>
 247 <p>
 248 In case none of our recommendations help and you are definitively having
 249 problems with idle connection drops, you can disable the use of persistent
 250 connections when using JK together with Apache httpd. For this you set
 251 "JkOptions +DisableReuse" in your Apache httpd configuration.
 252 This will have a huge negative performance impact!
 253 </p>
 254 </blockquote></td></tr></table>
 255
 256 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Reply Timeout"><strong>Reply Timeout</strong></a></font></td></tr><tr><td><blockquote>
 257 <p>
 258 JK can also use a timeout on request replies. This timeout does not
 259 measure the full processing time of the response. Instead it controls,
 260 how much time between consecutive response packets is allowed.
 261 </p>
 262 <p>
 263 In most cases, this is what one actually wants. Consider for example
 264 long running downloads. You would not be able to set an effective global
 265 reply timeout, because downloads could last for many minutes.
 266 Most applications though have limited processing time before starting
 267 to return the response. For those applications you could set an explicit
 268 reply timeout. Applications that do not harmonise with reply timeouts
 269 are batch type applications, data warehouse and reporting applications
 270 which are expected to observe long processing times.
 271 </p>
 272 <p><font color="#ff0000">
 273 If JK aborts waiting for a response, because a reply timeout fired,
 274 there is no way to stop processing on the backend. Although you free
 275 processing resources in your web server, the request
 276 will continue to run on the backend - without any way to send back a
 277 result once the reply timeout fired.
 278 </font></p>
 279 <p>
 280 JK uses the worker attribute <b>reply_timeout</b> to set reply timeouts.
 281 The default value is "0" (timeout disabled) and you can set it to any
 282 millisecond value.
 283 </p>
 284 <p>
 285 In combination with Apache httpd, you can also set a more flexible reply_timeout
 286 using an httpd environment variable. If you set the variable JK_REPLY_TIMEOUT
 287 to some integer value, this value will be used instead of the value in
 288 the worker configuration. This way you can set reply timeouts more flexible
 289 with mod_setenvif and mod_rewrite depending on URI, query string etc.
 290 If the environment variable JK_REPLY_TIMEOUT is not set, or is set to a
 291 negative value, the default reply timeout of the worker will be used. If
 292 JK_REPLY_TIMEOUT contains the value "0", then the reply timeout will be disabled
 293 for the request.
 294 </p>
 295 <p>
 296 In combination with a load balancing worker, JK will disable a member
 297 worker of the load balancer if a reply timeout fires. The worker will then
 298 no longer be used until it gets recovered during the next automatic
 299 maintenance task. Starting with JK 1.2.24 you can improve this behaviour using
 300 <b><a href="../../reference/workers.html">max_reply_timeouts</a></b>. This
 301 attribute will allow occasional long running requests without disabling the
 302 worker. Only if those requests happen to often, the worker gets disabled by the
 303 load balancer.
 304 </p>
 305 </blockquote></td></tr></table>
 306 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Load Balancer Error Detection"><strong>Load Balancer Error Detection</strong></a></font></td></tr><tr><td><blockquote>
 307 <br>
 308 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Local and Global Error States"><strong>Local and Global Error States</strong></a></font></td></tr><tr><td><blockquote>
 309 <p>
 310 A load balancer worker does not only have the ability to balance load.
 311 It also handles stickyness and failover of requests in case of errors.
 312 When a load balancer detects an error on one of its members, it needs to
 313 decide, whether the error is serious, or only a temporary error or maybe
 314 only related to the actual request that was processed. Temporary errors
 315 are called local errors, serious errors will be called global errors.
 316 </p>
 317 <p>
 318 If the load balancer decides that a backend should be put into the global error
 319 state, then the web server will not send any more requests there. If no session
 320 replication is used, this means that all user sessions located on the respective
 321 backend are no longer available. The users will be send to another backend
 322 and will have to login again. So the global error state is not transparent to the
 323 users. The application is still available, but users might loose some work.
 324 </p>
 325 <p>
 326 In some cases the decision between local error and global error is easy.
 327 For instance if there is an error sending back the response to the client (browser),
 328 then it is very unlikely that the backend is broken.
 329 So this situation is a typical example of a local error.
 330 </p>
 331 <p>
 332 Some situations are harder to decide though. If the load balancer can't establish
 333 a new connection to a backend, it could be because of a temporary overload situation
 334 (so no more free threads in the backend), or because the backend isn't alive any more.
 335 Depending on the details, the right state could either be local error or global error.
 336 </p>
 337 </blockquote></td></tr></table>
 338 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Error Escalation Time"><strong>Error Escalation Time</strong></a></font></td></tr><tr><td><blockquote>
 339 <p>
 340 Until version 1.2.26 most errors were interpreted as global errors.
 341 Starting with version 1.2.27 many errors which were previously interpreted as global
 342 were switched to being local whenever the backend is still busy. Busy means, that
 343 other concurrent requests are send to the same backend (successful or not).
 344 </p>
 345 <p>
 346 In many cases there is no perfect way of making the decision
 347 between local and global error. The load balancer simply doesn't have enough information.
 348 In version 1.2.28 you can now tune, how fast the load balancer switches from local error to
 349 global error. If a member of a load balancer stays in local error state for too long,
 350 the load balancer will escalate it into global error state.
 351 </p>
 352 <p>
 353 The time tolerated in local error state is controlled by the load balancer attribute
 354 <b>error_escalation_time</b> (in seconds). The default value is half of <b>recover_time</b>,
 355 so unless you changed <b>recover_time</b> the default is 30 seconds.
 356 </p>
 357 <p>
 358 Using a smaller value for <b>error_escalation_time</b> will make the load balancer react
 359 faster to serious errors, but also carries the risk of more often loosing sessions
 360 in not so serious situations. You can lower <b>error_escalation_time</b> down to 0 seconds,
 361 which means all local errors which are potentially serious are escalated to global errors
 362 immediately.
 363 </p>
 364 <p>
 365 Note that without good basic error detection the whole escalation procedure is useless.
 366 So you should definitely use <b>socket_connect_timeout</b> and activate CPing/CPong
 367 with <b>ping_mode</b> and <b>ping_timeout</b> before thinking about also tuning
 368 <b>error_escalation_time</b>.
 369 </p>
 370 </blockquote></td></tr></table>
 371 </blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
 372         Copyright &copy; 1999-2011, Apache Software Foundation
 373         </em></font></div></td></tr></table></body></html>