Folks, I've put in some updates to the mod_heart* modules, taken from the README supplied with the modules and some perusal of the source code. I have not run these as I'm too lazy to set up the servers. Review would be appreciated, especially by the original authors (Cc), before backport to 2.4.x.
Also added a doc file for mod_watchdog. Question for the docs folks: since this one is only of interest for consumption by other modules, how much documentation should we supply in the user-facing pages? I said "this module defines programmatic hooks"... do we need to define what the hook handler prototypes are? That's more like developer documentation. Thoughts? S. Begin forwarded message: > From: scte...@apache.org > Subject: svn commit: r1228700 - in /httpd/httpd/trunk/docs: STATUS > manual/mod/mod_heartbeat.xml manual/mod/mod_heartmonitor.xml > manual/mod/mod_watchdog.xml manual/mod/mod_watchdog.xml.meta > Date: January 7, 2012 11:10:29 AM PST > To: c...@httpd.apache.org > Reply-To: dev@httpd.apache.org > > Author: sctemme > Date: Sat Jan 7 19:10:28 2012 > New Revision: 1228700 > > URL: http://svn.apache.org/viewvc?rev=1228700&view=rev > Log: > Update heartbeat module documentation, add documentation for mod_watchdog > > Added: > httpd/httpd/trunk/docs/manual/mod/mod_watchdog.xml (with props) > httpd/httpd/trunk/docs/manual/mod/mod_watchdog.xml.meta > Modified: > httpd/httpd/trunk/docs/STATUS > httpd/httpd/trunk/docs/manual/mod/mod_heartbeat.xml > httpd/httpd/trunk/docs/manual/mod/mod_heartmonitor.xml > > Modified: httpd/httpd/trunk/docs/STATUS > URL: > http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/STATUS?rev=1228700&r1=1228699&r2=1228700&view=diff > ============================================================================== > --- httpd/httpd/trunk/docs/STATUS (original) > +++ httpd/httpd/trunk/docs/STATUS Sat Jan 7 19:10:28 2012 > @@ -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 > > Modified: httpd/httpd/trunk/docs/manual/mod/mod_heartbeat.xml > URL: > http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_heartbeat.xml?rev=1228700&r1=1228699&r2=1228700&view=diff > ============================================================================== > --- httpd/httpd/trunk/docs/manual/mod/mod_heartbeat.xml (original) > +++ httpd/httpd/trunk/docs/manual/mod/mod_heartbeat.xml Sat Jan 7 19:10:28 > 2012 > @@ -35,21 +35,66 @@ that advertises the servers current conn > 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&ready=75&busy=0 > +</example> > + > + <p> > + Consumers should handle new variables besides busy and ready, > + separated by '&', 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 > - address <module>mod_heartbeat</module> will send status information to. > This > - address will usually corrspond to a configured <directive > - module="mod_heartmonitor">HeartbeatListen</directive> on a frontend > - proxy system. </p> > +<p>The <directive>HeartbeatAddress</directive> directive specifies the > +multicast address to which <module>mod_heartbeat</module> will send > +status information. This address will usually correspond to a configured > + <directive module="mod_heartmonitor">HeartbeatListen</directive> on a > +frontend proxy system.</p> > +<example> > +HeartbeatAddress 239.0.0.1:27999 > +</example> > </usage> > </directivesynopsis> > > > Modified: httpd/httpd/trunk/docs/manual/mod/mod_heartmonitor.xml > URL: > http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_heartmonitor.xml?rev=1228700&r1=1228699&r2=1228700&view=diff > ============================================================================== > --- httpd/httpd/trunk/docs/manual/mod/mod_heartmonitor.xml (original) > +++ httpd/httpd/trunk/docs/manual/mod/mod_heartmonitor.xml Sat Jan 7 > 19:10:28 2012 > @@ -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_heartb > <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</descr > <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> > > Added: httpd/httpd/trunk/docs/manual/mod/mod_watchdog.xml > URL: > http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_watchdog.xml?rev=1228700&view=auto > ============================================================================== > --- httpd/httpd/trunk/docs/manual/mod/mod_watchdog.xml (added) > +++ httpd/httpd/trunk/docs/manual/mod/mod_watchdog.xml Sat Jan 7 19:10:28 > 2012 > @@ -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> > + > > Propchange: httpd/httpd/trunk/docs/manual/mod/mod_watchdog.xml > ------------------------------------------------------------------------------ > svn:eol-style = native > > Added: httpd/httpd/trunk/docs/manual/mod/mod_watchdog.xml.meta > URL: > http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_watchdog.xml.meta?rev=1228700&view=auto > ============================================================================== > --- httpd/httpd/trunk/docs/manual/mod/mod_watchdog.xml.meta (added) > +++ httpd/httpd/trunk/docs/manual/mod/mod_watchdog.xml.meta Sat Jan 7 > 19:10:28 2012 > @@ -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> > > -- scte...@apache.org http://www.temme.net/sander/ PGP FP: FC5A 6FC6 2E25 2DFD 8007 EE23 9BB8 63B0 F51B B88A View my availability: http://tungle.me/sctemme
