httpok Documentation¶

httpok is a supervisor “event listener” which may be subscribed to a concrete TICK_5, TICK_60 or TICK_3600 event. When httpok receives a TICK_x event (TICK_60 is recommended, indicating activity every 60 seconds), httpok makes an HTTP GET request to a confgured URL. If the request fails or times out, httpok will restart the “hung” child process(es). httpok can be configured to send an email notification when it restarts a process.

httpok can only monitor the process status of processes which are supervisord child processes.

httpok is a “console script” installed when you install superlance. Although httpok 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-Line Syntax¶

$ httpok [-p processname] [-a] [-g] [-t timeout] [-c status_code] \
         [-b inbody] [-m mail_address] [-s sendmail] URL

-p <process_name>, --program=<process_name>¶

Restart the 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 can be provided more than once to have httpok monitor more than one process.

To monitor a process which is part of a supervisord group, specify its name as group_name:process_name.

-a, --any¶

Restart any child of supervisord in the RUNNING state if the URL returns an unexpected result or times out.

Overrides any -p parameters passed in the same httpok process invocation.

-g <gcore_program>, --gcore=<gcore_program>¶: Use the specifed program to gcore the supervisord child process. The program should accept two arguments on the command line: a filename and a pid. Defaults to /usr/bin/gcore -o.

-d <core_directory>, --coredir=<core_directory>¶: If a core directory is specified, 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).

-t <timeout>, --timeout=<timeout>¶

The number of seconds that httpok should wait for a response to the HTTP request before timing out.

If this timeout is exceeded, httpok will attempt to restart child processes which are in the RUNNING state, and specified by -p or -a.

Defaults to 10 seconds.

-c <http_status_code>, --code=<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, httpok will attempt to restart child processes which are in the RUNNING state, and specified by -p or -a.

Defaults to 200.

-b <body_string>, --body=<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, 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.

-s <sendmail_command>, --sendmail_program=<sendmail_command>¶

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.

-m <email_address>, --email=<email_address>¶: Specify an email address to which notification messages are sent. If no email address is specified, email will not be sent.

-e, --eager¶

Enable “eager” monitoring: check the URL and emit mail even if no monitored child process is in the RUNNING state.

Enabled by default.

-E, --not-eager¶: Disable “eager” monitoring: do not check the URL or emit mail if no monitored process is in the RUNNING state.

URL¶: The URL to which to issue a GET request.

-n <httpok name>, --name=<httpok name>¶: An optional name that identifies this httpok process. If given, the email subject will start with httpok [<httpok name>]: instead of httpok: In case you run multiple supervisors on a single host that control different processes with the same name (eg zopeinstance1) you can use this option to indicate which project the restarted instance belongs to.

Configuring httpok Into the Supervisor Config¶

An [eventlistener:x] section must be placed in supervisord.conf in order for httpok to do its work. See the “Events” chapter in the Supervisor manual for more information about event listeners.

The following example assumes that httpok is on your system PATH.

[eventlistener:httpok]
command=httpok -p program1 -p group1:program2 http://localhost:8080/tasty
events=TICK_60