Update heartbeat module documentation, add documentation for mod_watchdog

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1228700 13f79535-47bb-0310-9956-ffa450edef68

docs/STATUS

@@ -56,12 +56,8 @@ To Do List
   Start is in expr.xml, igalic is working on this
 
 - modules docs
-    - the follwing modules added since 2.2 lack documentation
+    - the following modules added since 2.2 lack documentation
         - mod_serf
-        - mod_watchdog
-        - mod_heartbeat
-        - mod_heartmonitor
-        - mod_lbmethod_heartbeat
         - mpm_simple
       the list may be incomplete
       maybe some of the modules will not be included in 2.4

docs/manual/mod/mod_heartbeat.xml

@@ -35,21 +35,66 @@ that advertises the servers current connection count.  Usually, <module>mod_hear
 will be running on a proxy server with <module>mod_lbmethod_heartbeat</module> loaded, which allows
 <directive module="mod_proxy">ProxyPass</directive> to use the "heartbeat" <em>lbmethod</em> inside
 of <directive module="mod_proxy">ProxyPass</directive>.</p>
+<p>
+    <module>mod_heartbeat</module> itself is loaded on the origin server(s) that serve requests 
+    through the proxy server(s).  
+</p>
+
+    <note type="warning">
+        To use <module>mod_heartbeat</module>,
+        <module>mod_status</module> and <module>mod_watchdog</module>
+        must be either a static modules or, if a dynamic module, it must
+        be loaded before <module>mod_heartbeat</module>.
+    </note>
+
 </summary>
 
+<section id="consuming">
+    <title>Consuming mod_heartbeat Output</title>
+  <p>
+      Every 1 second, this module generates a single multicast UDP
+      packet, containing the number of busy and idle workers.  The
+      packet is a simple ASCII format, similiar to GET query parameters
+      in HTTP.
+  </p>
+  
+<example><title>An Example Packet</title>
+v=1&amp;ready=75&amp;busy=0
+</example>
+
+  <p>
+    Consumers should handle new variables besides busy and ready,
+    separated by '&amp;', being added in the future.
+  </p>
+
+</section>
+
+<section id="miscellaneous">
+<title>Miscellaneous</title>
+<p>The interval of 1 seconds is controlled by the HEARTBEAT_INTERVAL
+compile time define.  This is not currently tunable at run time. To make
+this module send the status packet more often, you must add to the
+CFLAGS used to compile the module to include:</p>
+<example>-DHEARTBEAT_INTERVAL=3</example>
+<p>Would cause the broadcasts to be sent every 3 seconds.</p>
+</section>    
+
 <directivesynopsis>
 <name>HeartbeatAddress</name>
-<description>Address to send heartbeat requests</description>
+<description>Multicast address for heartbeat packets</description>
 <syntax>HeartbeatAddress <var>addr:port</var></syntax>
 <default>disabled</default>
 <contextlist><context>server config</context></contextlist>
 
 <usage>
-    <p>The <directive>HeartbeatAddress</directive> directive specifies the 
+<p>The <directive>HeartbeatAddress</directive> directive specifies the
-    address <module>mod_heartbeat</module> will send status information to. This
+multicast address to which <module>mod_heartbeat</module> will send
-    address will usually corrspond to a configured  <directive
+status information. This address will usually correspond to a configured
-    module="mod_heartmonitor">HeartbeatListen</directive> on a frontend
+ <directive module="mod_heartmonitor">HeartbeatListen</directive> on a
-    proxy system.  </p>
+frontend proxy system.</p>
+<example>
+HeartbeatAddress 239.0.0.1:27999
+</example>    
 </usage>
 </directivesynopsis>
 

docs/manual/mod/mod_heartmonitor.xml

@@ -20,19 +20,19 @@
  limitations under the License.
 -->
 
-<modulesynopsis metafile="mod_heartbeat.xml.meta">
+<modulesynopsis metafile="mod_heartmonitor.xml.meta">
 
 <name>mod_heartmonitor</name>
 <description>centralized monitor for mod_heartbeat origin servers</description>
 <status>Experimental</status>
-<sourcefile>mod_heartmonitor</sourcefile>
+<sourcefile>mod_heartmonitor.c</sourcefile>
 <identifier>heartmonitor_module</identifier>
 <compatibility>Available in Apache 2.3 and later</compatibility>
 
 <summary>
 <p>
 <module>mod_heartmonitor</module> listens for server status messages generated 
-by <module>mod_heartbeat</module> enabled servers and makes their status 
+by <module>mod_heartbeat</module> enabled origin servers and makes their status 
 available to <module>mod_lbmethod_heartbeat</module>. This allows 
 <directive module="mod_proxy">ProxyPass</directive> to use the "heartbeat" 
 <em>lbmethod</em> inside of <directive module="mod_proxy">ProxyPass</directive>.
@@ -41,22 +41,34 @@ available to <module>mod_lbmethod_heartbeat</module>. This allows
 <p>This module uses the services of <module>mod_slotmem_shm</module> when
 available instead of flat-file storage.  No configuration is required to
 use <module>mod_slotmem_shm</module>.</p>
+
+    <note type="warning">
+        To use <module>mod_heartmonitor</module>,
+        <module>mod_status</module> and <module>mod_watchdog</module>
+        must be either a static modules or, if a dynamic module, it must
+        be loaded before <module>mod_heartmonitor</module>.
+    </note>
+
 </summary>
 
 <directivesynopsis>
 <name>HeartbeatListen</name>
-<description>address to listen for incoming heartbeat requests </description>
+<description>multicast address to listen for incoming heartbeat requests </description>
 <syntax>HeartbeatListen<var>addr:port</var></syntax>
 <default>disabled</default>
 <contextlist><context>server config</context></contextlist>
 
 <usage>
     <p>The <directive>HeartbeatListen</directive> directive specifies the
-    address the server will listen on for status information from 
+    multicast address on which the server will listen for status information from 
     <module>mod_heartbeat</module>-enabled servers.  This
     address will usually corrspond to a configured  <directive
     module="mod_heartbeat">HeartbeatAddress</directive> on an origin server.
     </p>
+    
+    <example>
+    HeartbeatListen 239.0.0.1:27999
+    </example>
 
     <p> This module is inactive until this directive is used.</p>
 </usage>
@@ -88,7 +100,7 @@ heartbeat requests to this server</description>
     <p>The <directive>HeartbeatMaxServers</directive> directive specifies the
     maximum number of servers that will be sending requests to this monitor
     server.  It is used to control the size of the shared memory allocated
-    to store the heartbeat info.</p>
+    to store the heartbeat info when <module>mod_slotmem_shm</module> is in use.</p>
 </usage>
 </directivesynopsis>
 </modulesynopsis>

docs/manual/mod/mod_watchdog.xml

@@ -0,0 +1,60 @@
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+<!--
+ 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.
+-->
+
+<modulesynopsis metafile="mod_watchdog.xml.meta">
+<name>mod_watchdog</name>
+<description>provides infrastructure for other modules to periodically run 
+    tasks</description>
+<status>Base</status>
+<sourcefile>mod_watchdog.c</sourcefile>
+<identifier>watchdog_module</identifier>
+<compatibility>Available in Apache 2.3 and later</compatibility>
+
+<summary>
+<p><module>mod_watchdog</module> defines programmatic hooks for other modules to 
+periodically run tasks.  These modules can register handlers for 
+<module>mod_watchdog</module> hooks.  Currently, the following modules in the 
+Apache distribution use this functionality:</p> 
+<ul>
+<li><module>mod_heartbeat</module></li>
+<li><module>mod_heartmonitor</module></li>
+</ul>
+<note type="warning">
+To allow a module to use <module>mod_watchdog</module> functionality, 
+<module>mod_watchdog</module> itself must be statically linked to the server 
+core or, if a dynamic module, be loaded before the calling module. 
+</note>
+</summary>
+
+<directivesynopsis>
+<name>WatchdogInterval</name>
+<description>Watchdog interval in seconds</description>
+<syntax>WatchdogInterval <var>number-of-seconds</var></syntax>
+<default>WatchdogInterval 1</default>
+<contextlist><context>server config</context></contextlist>
+
+<usage>
+Sets the interval at which the watchdog_step hook runs.  Default is to run every 
+second.
+</usage>
+</directivesynopsis>
+</modulesynopsis>
+

docs/manual/mod/mod_watchdog.xml.meta

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- GENERATED FROM XML: DO NOT EDIT -->
+
+<metafile reference="mod_watchdog.xml">
+  <basename>mod_watchdog</basename>
+  <path>/mod/</path>
+  <relpath>..</relpath>
+
+  <variants>
+    <variant>en</variant>
+  </variants>
+</metafile>