httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sander Temme <scte...@apache.org>
Subject Fwd: 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 Sat, 07 Jan 2012 19:22:04 GMT
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: sctemme@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: cvs@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&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 
> -    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>
> 
> 


-- 
sctemme@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



Mime
View raw message