Author: rjung
Date: Fri Oct 24 10:27:25 2008
New Revision: 707690
URL: http://svn.apache.org/viewvc?rev=707690&view=rev
Log:
Add some more info about the new CPing/CPong
configuration to the docs.
Modified:
tomcat/connectors/trunk/jk/xdocs/generic_howto/timeouts.xml
tomcat/connectors/trunk/jk/xdocs/miscellaneous/changelog.xml
tomcat/connectors/trunk/jk/xdocs/reference/workers.xml
Modified: tomcat/connectors/trunk/jk/xdocs/generic_howto/timeouts.xml
URL:
http://svn.apache.org/viewvc/tomcat/connectors/trunk/jk/xdocs/generic_howto/timeouts.xml?rev=707690&r1=707689&r2=707690&view=diff
==============================================================================
--- tomcat/connectors/trunk/jk/xdocs/generic_howto/timeouts.xml (original)
+++ tomcat/connectors/trunk/jk/xdocs/generic_howto/timeouts.xml Fri Oct 24
10:27:25 2008
@@ -58,8 +58,12 @@
<p>
CPing/CPong is our notion for using small test packets to check the
status of backend connections. JK can use such test packets directly after
establishing
-a new backend connection and also directly before each request gets send to a
backend.
-The maximum waiting time for a CPong answer to a CPing can be configured.
+a new backend connection (connect mode) and also directly before each request
gets
+send to a backend (prepost mode).
+Starting with version 1.2.27 it can also be used when a connection was idle
+for a long time (interval mode).
+The maximum waiting time (timeout) for a CPong answer to a CPing and the idle
+time in interval mode can be configured.
</p>
<p>
The test packets will be answered by the backend very fast with a minimal
amount of
@@ -69,21 +73,64 @@
problem with the backend. The downside is a slightly increased latency.
</p>
<p>
-The worker attribute <b>connect_timeout</b> sets the wait timeout for CPong
during
-connection establishment. By default the value is "0", which disables
CPing/CPong during
-connection establishment. Since JK usually uses persistent connections,
opening new connections
-is a rare event. We therefore recommend using <b>connect_timeout</b>. Its
value is given
-in milliseconds. Depending on your network latency and stability, good values
often
-are between 5000 and 15000 milliseconds. Remember: don't use extremely small
values.
+The worker attribute <b>ping_mode</b> can be set to a combination of characters
+to determine, in which situations test packets are used:
+<ul>
+<li><b>C</b>: connect mode, timeout <b>ping_timeout</b> overwritten by
<b>connect_timeout</b></li>
+<li><b>P</b>: prepost mode, timeout <b>ping_timeout</b> overwritten by
<b>prepost_timeout</b></li>
+<li><b>I</b>: interval mode, timeout <b>ping_timeout</b>, idle time
<b>connection_ping_interval</b></li>
+<li><b>A</b>: all modes</li>
+</ul>
+</p>
+<p>
+Multiple values must be concatenated without any separator characters.
+We recommend using all CPing tests. If your application is very latency
sensitive, then
+you should only use the combination of connect and interval mode.
+</p>
+<p>
+Activating the CPing probing via <b>ping_mode</b> has been added in version
1.2.27.
+For older versions only the connect and prepost modes exist and must be
activated by
+explicitely setting <b>connect_timeout</b> and <b>prepost_timeout</b>.
+</p>
+<p>
+The worker attribute <b>ping_timeout</b> sets the default wait timeout
+in milliseconds for CPong for all modes. By default the value is "10000"
+milliseconds. The value only gets used, if you activate CPing/Cpong probes
+via <b>ping_mode</b>. The default value should be fine, except if you
experience
+very long Java garbage collection pauses.
+Depending on your network latency and stability, good custom values
+often are between 5000 and 15000 milliseconds.
+You can overwrite the timeout used for connect and prepost mode with
+<b>connect_timeout</b> and <b>prepost_timeout</b>.
+Remember: don't use extremely small values.
+</p>
+<p>
+The worker attribute <b>connect_timeout</b> sets the wait timeout
+in milliseconds for CPong during connection establishment. You can use it
+if you want to overwrite the general timeout set with <b>ping_timeout</b>.
+To use connect mode CPing, you need to enable it via <b>ping_mode</b>.
+Since JK usually uses persistent connections, opening new connections is a
+rare event. We therefore recommend activating connect mode.
+Depending on your network latency and stability, good values often
+are between 5000 and 15000 milliseconds.
+Remember: don't use extremely small values.
+</p>
+<p>
+The worker attribute <b>prepost_timeout</b> sets the wait timeout
+in milliseconds for CPong before request forwarding. You can use it
+if you want to overwrite the general timeout set with <b>ping_timeout</b>.
+To use prepost mode CPing, you need to enable it via <b>ping_mode</b>.
+Activating this type of CPing/CPong adds a small latency to each
+request. Usually this is small enough and the benefit of CPing/CPong is more
important.
+So in general we also recommend using <b>prepost_timeout</b>.
+Depending on your network latency and stability, good values often
+are between 5000 and 10000 milliseconds.
+Remember: don't use extremely small values.
</p>
<p>
-The worker attribute <b>prepost_timeout</b> sets the wait timeout for CPong
before
-request forwarding. By default the value is "0", which disables CPing/CPong
before
-request forwarding. Activating this type of CPing/CPong adds a small latency
to each
-request. Usually this is small enough and the benefit of CPing/CPong is more
important.
-In general we also recommend using <b>prepost_timeout</b>. Its value is given
-in milliseconds. Depending on your network latency and stability, good values
often
-are between 5000 and 10000 milliseconds. Remember: don't use extremely small
values.
+Until version 1.2.27 <b>ping_mode</b> and <b>ping_timeout</b> did not
+exist and to enable connect or prepost mode CPing you had to set
<b>connect_timeout</b>
+respectively <b>prepost_timeout</b> to some reasonable positive value.
</p>
</subsection>
@@ -112,6 +159,16 @@
problems, or only because it didn't receive an answer packet from a backend in
time.
So remember: don't use extremely small values.
</p>
+<p>
+For the general case of connection establishment you can use
+<b>socket_connect_timeout</b>. It takes a millisecond value and works
+on most platforms, even if <b>socket_timeout</b> is not supported.
+We recommend using <b>socket_connect_timeout</b> because in some network
+failure situations failure detection during connection establishment
+can take several minutes due to TCP retransmits. Depending on the quality
+of your network a timeout somewhere between 1000 and 5000 milliseconds
+should be fine.
+</p>
</subsection>
<subsection name="Connection Pools and Idle Timeouts">
Modified: tomcat/connectors/trunk/jk/xdocs/miscellaneous/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/connectors/trunk/jk/xdocs/miscellaneous/changelog.xml?rev=707690&r1=707689&r2=707690&view=diff
==============================================================================
--- tomcat/connectors/trunk/jk/xdocs/miscellaneous/changelog.xml (original)
+++ tomcat/connectors/trunk/jk/xdocs/miscellaneous/changelog.xml Fri Oct 24
10:27:25 2008
@@ -282,8 +282,8 @@
web server specific code to our generic jk_init_ws_service() function.
(rjung)
</update>
<fix>
- <bug>36385</bug>: Add missing prepost cping/cpong directly after
connect
- in case prepost cping is used, but no connect cping. (rjung)
+ <bug>36385</bug>: Add missing prepost CPing/CPong directly after
connect
+ in case prepost CPing is used, but no connect CPing. (rjung)
</fix>
<update>
<bug>37322</bug>: Apache: Enhance robustness of message formating
Modified: tomcat/connectors/trunk/jk/xdocs/reference/workers.xml
URL:
http://svn.apache.org/viewvc/tomcat/connectors/trunk/jk/xdocs/reference/workers.xml?rev=707690&r1=707689&r2=707690&view=diff
==============================================================================
--- tomcat/connectors/trunk/jk/xdocs/reference/workers.xml (original)
+++ tomcat/connectors/trunk/jk/xdocs/reference/workers.xml Fri Oct 24 10:27:25
2008
@@ -269,45 +269,73 @@
</p>
</directive>
-<directive name="connection_ping_interval" default="0" required="false">
-Connections idle for longer than this interval in seconds are probed by
-CPING packets whether they still work. If set to zero (default),
-no such probes will be done.
-<p>To be able to use this feature <code>ping_timeout</code> must be
-set to the desired timeout value and <code>ping_mode</code> must include
-<code>I</code> flag.
-</p>
-<p>
-This feature has been added in <b>jk 1.2.27</b>.
+<directive name="ping_mode" default="" required="false">
+This flag determines, under which conditions established
+connections are probed to ensure they are still working.
+The probe is done with an empty AJP13 packet (CPing) and
+expects to receive an appropriate answer (CPong) within
+some timeout.
+<p>
+The value of the flag can be any combination of the following
+flags (multiple values are combined without any separators):
+</p>
+<p><b>C</b> (connect): If set, the connection will
+be probed once after connecting to the backend. The timeout
+can be set by <code>connect_timeout</code>. If it is not set,
+the value of <code>ping_timeout</code> will be used instead.
+</p>
+<p><b>P</b> (prepost): If set, the connection will
+be probed before sending each request to the backend. The timeout
+can be set by <code>prepost_timeout</code>. If it is not set,
+the value of <code>ping_timeout</code> will be used instead.
+</p>
+<p><b>I</b> (interval): If set, the connection will
+be probed during the regular internal maintenance cycle,
+but only if it is idle longer than
+<code>connection_ping_interval</code>. The timeout
+can be set by <code>ping_timeout</code>.
+</p>
+<p><b>A</b> If set, all of the above probes will be used.
+</p>
+<p>
+This feature has been added in <b>jk 1.2.27</b>. Connect and
+prepost probing were already available via <code>connect_timeout</code>
+and <code>prepost_timeout</code> since version <b>jk 1.2.6</b>.
</p>
</directive>
<directive name="ping_timeout" default="10000" required="false">
-Connections idle for longer than this interval in milliseconds are probed by
-CPING packets whether they still work. The usage depend on the
-<code>ping_mode</code> flags used.
+Timeout in milliseconds used when waiting for the CPong answer of a
+CPing connection probe. The activation of the probes is done via
+<code>ping_mode</code>. The timeouts for <code>ping_mode</code>
+connect and prepost can be overwritten individually via
+<code>connect_timeout</code> and <code>prepost_timeout</code>.
+<p>
+For compatibility reasons, CPing/CPong is also used, whenever
+<code>connect_timeout</code> or <code>prepost_timeout</code> are set,
+even if <code>ping_mode</code> is empty.
+</p>
<p>
This feature has been added in <b>jk 1.2.27</b>.
</p>
</directive>
-<directive name="ping_mode" default="" required="false">
-Ping mode flags for active connections. The value can
-be combination of the following flags:
-<p><b>C</b> If set the connect ping mode will be used. If
-directive <code>connect_timeout</code> was not set, the
-value of <code>ping_timeout</code> will be used instead.
-</p>
-<p><b>P</b> If set the prepost ping mode will be used. If
-directive <code>prepost_timeout</code> was not set, the
-value of <code>ping_timeout</code> will be used instead.
-</p>
-<p><b>I</b> If set the interval ping mode will be used. If
+The usage depend on the <code>ping_mode</code> flags used.
directive <code>connection_ping_interval</code> was not set, the
-value of <code>ping_timeout * 10</code> will be used as
+value of <code>(ping_timeout/1000) * 10</code> will be used as
<code>connection_ping_interval</code> value.
-</p>
-<p><b>A</b> If set all of the mode above will be used.
+
+<directive name="connection_ping_interval" default="0 /
(ping_timeout/1000)*10" required="false">
+When using interval connection probing, connections idle for longer than this
+interval in seconds are probed by CPing packets whether they still work.
+<p>Interval probing can be activated either by <code>ping_mode</code>,
+or by setting <code>connection_ping_interval</code> to some value bigger
+than zero. If you activate interval probing via <code>ping_mode</code>,
+then the default value of <code>connection_ping_interval</code> is
+<code>(ping_timeout/1000) * 10</code>. Note that <code>ping_timeout</code>
+is in milliseconds, and <code>connection_ping_interval</code> in seconds,
+so in absolute terms the default <code>connection_ping_interval</code> is
+10 times <code>ping_timeout</code>.
</p>
<p>
This feature has been added in <b>jk 1.2.27</b>.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
