Commits

Tres Seaver committed 7cc27d7

[svn r969] Add httpok docs; tweak the rest.

Comments (0)

Files changed (4)

trunk/docs/crashmail.rst

 :command:`crashmail` Documentation
 ==================================
 
+:command:`crashmail` is a supervisor "event listener", intended to be
+subscribed to ``PROCESS_STATE_EXITED`` events. When :command:`crashmail`
+receives that event, and the transition is "unexpected", :command:`crashmail``
+sends an email notification to a configured address..
+
+:command:`crashmail` is incapable of monitoring the process status of processes
+which are not :command:`supervisord` child processes.
+
+:command:`crashmail` is a "console script" installed when you install
+:mod:`superlance`.  Although :command:`crashmail` is an executable program, it
+isn't useful as a general-purpose script:  it must be run as a
+:command:`supervisor` event listener to do anything useful.
+
 Command-Line Syntax
 -------------------
 
+.. code-block:: sh
+
+   $ crashmail.py [-p processname] [-a] [-o string] [-m mail_address] \
+                  [-s sendmail]
+
 .. program:: crashmail
 
 .. cmdoption:: -p <process_name>
 -----------------------------------------------------------
 
 An ``[eventlistener:x]`` section must be placed in :file:`supervisord.conf`
-in order for :command:`memmon` to do its work. See the "Events" chapter in the
-Supervisor manual for more information about event listeners.
+in order for :command:`crashmail` to do its work. See the "Events" chapter in
+the Supervisor manual for more information about event listeners.
 
 The following example assumes that :command:`crashmail` is on your system
 :envvar:`PATH`.

trunk/docs/httpok.rst

+:command:`httpok` Documentation
+==================================
+
+:command:`httpok` is a supervisor "event listener" which may be subscribed to
+a concrete ``TICK_x`` event. When :command:`httpok` receives a ``TICK_x``
+event (``TICK_60`` is recommended, indicating activity every 60 seconds),
+:command:`httpk` makes an HTTP GET request to a confgured URL. If the request
+fails or times out, :command:`httpok`` will restart the "hung" child
+process(es). :command:`httpok` can be configured to send an email notification
+when it restarts a process.
+
+:command:`httpok` is incapable of monitoring the process status of processes
+which are not :command:`supervisord` child processes.
+
+:command:`httpok` is a "console script" installed when you install
+:mod:`superlance`.  Although :command:`httpok` is an executable program, it
+isn't useful as a general-purpose script:  it must be run as a
+:command:`supervisor` event listener to do anything useful.
+
+Command-Line Syntax
+-------------------
+
+.. code-block:: sh
+
+   $ httpok.py [-p processname] [-a] [-g] [-t timeout] [-c status_code] \
+               [-b inbody] [-m mail_address] [-s sendmail] URL
+
+.. program:: httpok
+
+.. cmdoption:: -p <process_name>
+   
+   Restart the :command:`supervisord` child process named ``process_name``
+   if it is in the ``RUNNING`` state when the URL returns an unexpected
+   result or times out.
+
+   This option may be specified more than once, allowing for specification
+   of multiple processes.
+   
+   To monitor a process which is part of a :command:`supervisord` group,
+   specify its name as ``process_name:group_name``.
+
+.. cmdoption:: -a
+   
+   Restart any child of :command:`supervisord` in the RUNNING state
+   if the URL returns an unexpected result or times out.
+    
+   Overrides any ``-p`` parameters passed in the same :command:`httpok`
+   process invocation.
+
+.. cmdoption:: -g <gcore_program>
+   
+   Use the specifed program to ``gcore`` the :command:`supervisord` child
+   process.  The program should accept two arguments on the command line:
+   a filename and a pid.  Defaults to ``/usr/bin/gcore -o``.
+
+.. cmdoption:: -d <core_directory>
+   
+   If a core directory is specified, :command:`httpok` will try to use the
+   ``gcore`` program (see ``-g``) to write a core file into this directory
+   for each hung process before restarting it.  It will then append any gcore
+   stdout output to the email message, if mail is configured (see the ``-m``
+   option below).
+
+.. cmdoption:: -t <timeout>
+   
+   The number of seconds that :command:`httpok` should wait for a response
+   to the HTTP request before timing out.
+   
+   If this timeout is exceeded, :command:`httpok` will attempt to restart
+   child processes which are in the ``RUNNING state, and specified by
+   ``-p`` or ``-a``.
+
+   Defaults to 10 seconds.
+
+.. cmdoption:: -c <http_status_code>
+   
+   Specify the expected HTTP status code for the configured URL.
+   
+   If this status code is not the status code provided by the response,
+   :command:`httpok` will attempt to restart child processes which are
+   in the ``RUNNING`` state, and specified by ``-p`` or ``-a``.  
+   
+   Defaults to the string, "200".
+
+.. cmdoption:: -b <body_string>
+   
+   Specify a string which should be present in the body resulting
+   from the GET request.
+   
+   If this string is not present in the response, :command:`httpok` will
+   attempt to restart child processes which are in the RUNNING state,
+   and specified by ``-p`` or ``-a``.
+   
+   The default is to ignore the body.
+
+.. cmdoption:: -s
+   
+   Specify the sendmail command to use to send email.
+   
+   Must be a command which accepts header and message data on stdin and
+   sends mail.  Default is ``/usr/sbin/sendmail -t -i``.
+
+.. cmdoption:: -m
+   
+   Specify an email address to which notification messages are sent.
+   If no email address is specified, email will not be sent.
+
+.. cmdoption:: -e
+   
+   Enable "eager" monitoring:  check the URL and emit mail even if no
+   monitored child process is in the ``RUNNING`` state.
+   
+   Enabled by default.
+
+.. cmdoption:: -E
+   
+   Disable "eager" monitoring:  do not check the URL or emit mail if no
+   monitored process is in the RUNNING state.
+
+.. cmdoption:: <URL>
+   
+   The URL to which to issue a GET request.
+
+
+Configuring :command:`httpok` Into the Supervisor Config
+-----------------------------------------------------------
+
+An ``[eventlistener:x]`` section must be placed in :file:`supervisord.conf`
+in order for :command:`memmon` to do its work. See the "Events" chapter in the
+Supervisor manual for more information about event listeners.
+
+The following example assumes that :command:`httpok` is on your system
+:envvar:`PATH`.
+
+.. code-block:: ini
+
+   [eventlistener:httpok]
+   httpok.py -p program1 -p group1:program2 http://localhost:8080/tasty
+   events=TICK_60

trunk/docs/index.rst

 .. toctree::
    :maxdepth: 2
 
+   httpok
+   crashmail
    memmon
-   crashmail
 
 Indices and tables
 ==================

trunk/docs/memmon.rst

 ==========================
 
 :command:`memmon` is a supervisor "event listener" which may be subscribed to
-a concrete ``TICK_x`` event. When memmon receives a ``TICK_x`` event (
-``TICK_60`` is recommended, indicating activity every 60 seconds),
+a concrete ``TICK_x`` event. When :command:`memmon` receives a ``TICK_x``
+event (``TICK_60`` is recommended, indicating activity every 60 seconds),
 :command:`memmon` checks that a configurable list of programs (or all
 programs running under supervisor) are not exceeding a configurable about of
 memory (resident segment size, or RSS).  If one or more of these processes is
 command-line switches).
 
 :command:`memmon` is incapable of monitoring the process status of processes
-which are not supervisord child processes.
+which are not :command:`supervisord` child processes.
+
+:command:`memmon` is a "console script" installed when you install
+:mod:`superlance`.  Although :command:`memmon` is an executable program, it
+isn't useful as a general-purpose script:  it must be run as a
+:command:`supervisor` event listener to do anything useful.
 
 Command-Line Syntax
 -------------------
 
-:command:`memmon` is a "console script" installed when you install supervisor.
-Although memmon is an executable program, it isn't useful as a general-purpose
-script:  it must be run as a supervisor event listener to do anything useful.
-
 :command:`memmon` accepts the following options:
 
 .. program:: memmon