skip to navigation
skip to content

collective.recipe.supervisor 0.5

A buildout recipe to install supervisor

Latest Version: 0.20

Change history

0.5 (2008-08-23)

  • Adding eventlistners option for use as event notification framework. Targetting use with supervisor’s memmon event listener [aburkhalter]

0.4 (2008-06-12)

  • Use dynamic script names to allow multiple cluster [gawel]
  • Ensure that the log dir is created when used without zope’s recipes [gawel]

0.3 (2008-06-01)

  • Updated docs and tests [mustapha]
  • pep8 cosmetics [mustapha]
  • Make it possible to pass in arguments to the control script. [hannosch]
  • Put all specified options, like server url and username into the generated control script. This allows to run it as is. [hannosch]

0.2 (2008-04-23)

  • Make possible to pass arguments to the command so one can use ctl scripts with supervisor with arguments like ‘fg’ for zope instances or –no-detach or something similar for other programs [mustapha]
  • updated tests [mustapha]

0.1 (2008-04-21)

  • Created recipe with ZopeSkel [Mustapha Benali].

Detailed Documentation

This recipe when used will do the following:

  • install supervisor and all its dependecies.
  • generates the supervisord, supervisorctl, and memmon scripts in the bin directory
  • generates a configuration file to be used by supervisord and supervisorctl scripts

Supported options

The recipe supports the following options:

The port nummber supervisord listen to. ie: 9001. Can be given as host:port like Defaults to
The username required for authentication to supervisord
The password required for authentication to supervisord
Full path to where the recipe puts the supervisord configuration file. Defaults to ${buildout:directory}/parts/${name}/supervisord.conf
The full path to the supervisord log file. Defaults to ${buildout:directory}/var/log/supervisord.log
The pid file of supervisord. Defaults to ${buildout:directory}/var/
The maximum number of bytes that may be consumed by the activity log file before it is rotated. Defaults to 50MB
The number of backups to keep around resulting from activity log file rotation. Defaults to 10
The logging level. Can be one of critical, error, warn, info, debug, trace, or blather. Defaults to info
If true, supervisord will start in the foreground instead of daemonizing. Defaults to false
The URL that should be used to access the supervisord server. Defaults to

A list of programs you want the supervisord to control. One per line. The format of a line is as follow:

priority process_name command [[args] [directory] [[redirect_stderr]]]

The [args] is any number of arguments you want to pass to the command It has to be given between [] (ie.: [-v fg]). See examples below. If not given the redirect_stderr defaults to false. If not given the directory option defaults to the directory containing the the command.

In most cases you will only need to give the 4 first parts:

priority process_name command [[args]]

A list of eventlisteners you’d like supervisord to run as subprocesses to subscribe to event notifications. One per line. Relevant supervisor documentation about events at

events command [[args]]

Supervisor provides one such event listener called memmon which can be used to restart supervisord child process once they reach a certain memory limit. An example of defining a memmon event listener, which analyzes memory usage every 60 seconds and restarts as needed could look like:

TICK_60 ${buildout:bin-directory}/memmon [-p process_name=200MB]

Example usage

We’ll start by creating a buildout that uses the recipe:

>>> write('buildout.cfg',
... """
... [buildout]
... parts = supervisor
... index =
... [zeo]
... location = /a/b/c
... [instance1]
... location = /e/f
... [instance2]
... location = /g/h
... [supervisor]
... recipe = collective.recipe.supervisor
... port = 9001
... user = mustapha
... password = secret
... serverurl =
... programs =
...       10 zeo ${zeo:location}/bin/runzeo ${zeo:location}
...       20 instance1 ${instance1:location}/bin/runzope ${instance1:location} true
...       30 instance2 ${instance2:location}/bin/runzope true
...       40 maildrophost ${buildout:bin-directory}/maildropctl true
...       50 other ${buildout:bin-directory}/other [-n 100] /tmp
...       60 other2 ${buildout:bin-directory}/other2 [-n 100] true
...       70 other3 ${buildout:bin-directory}/other3 [-n -h -v --no-detach] /tmp3 true
... eventlisteners =
...       TICK_60 ${buildout:bin-directory}/memmon [-p instance1=200MB]
... """)

Chris Mc Donough said:

Note however that the "instance" script Plone uses to start Zope when
passed "fg" appears to use os.system, so the process that supervisor is
controlling isnt actually Plone, it's the controller script. This means
that "stop" and "start" tend to not do what you want. It's far better to
use "runzope", which actually execs the Python process which becomes Zope
See also

Running the buildout gives us:

>>> print system(buildout)
Installing supervisor.
Getting distribution for 'supervisor'.
Generated script '/sample-buildout/bin/supervisord'.
Generated script '/sample-buildout/bin/memmon'.
Generated script '/sample-buildout/bin/supervisorctl'.

You can now just run the supervisord like this:

$ bin/supervisord

and control it with supervisorctl:

$ bin/supervisorctl

Memory monitoring via supervisor’s memmon event listener will be executed via supervisord with the following:

$ bin/memmon

now, get a look to the generated supervisord.conf file:

>>> cat('parts', 'supervisor', 'supervisord.conf')
port = 9001
username = mustapha
password = secret
logfile = /sample-buildout/var/log/supervisord.log
logfile_maxbytes = 50MB
logfile_backups = 10
loglevel = info
pidfile = /sample-buildout/var/
nodaemon = false
serverurl =
command = /a/b/c/bin/runzeo
process_name = zeo
directory = /a/b/c
priority = 10
redirect_stderr = false
command = /e/f/bin/runzope
process_name = instance1
directory = /e/f
priority = 20
redirect_stderr = true
command = /g/h/bin/runzope
process_name = instance2
directory = /g/h/bin
priority = 30
redirect_stderr = true
command = /sample-buildout/bin/maildropctl
process_name = maildrophost
directory = /sample-buildout/bin
priority = 40
redirect_stderr = true
command = /sample-buildout/bin/other -n 100
process_name = other
directory = /tmp
priority = 50
redirect_stderr = false
command = /sample-buildout/bin/other2 -n 100
process_name = other2
directory = /sample-buildout/bin
priority = 60
redirect_stderr = true
command = /sample-buildout/bin/other3 -n -h -v --no-detach
process_name = other3
directory = /tmp3
priority = 70
redirect_stderr = true
command = /sample-buildout/bin/memmon -p instance1=200MB
events = TICK_60

and if we look to generated supervisord script we will see that the configuration file is given as argument with the ‘-c’ option:

>>> cat('bin', 'supervisord')
import sys; sys.argv.extend(["-c","/sample-buildout/parts/supervisor/supervisord.conf"])
import supervisor.supervisord
if __name__ == '__main__':

The control script contains all specified options, like server url and username. This allows to run it as is:

>>> cat('bin', 'supervisorctl')
import sys; sys.argv[1:1] = ["-c","/sample-buildout/parts/supervisor/supervisord.conf","-u","mustapha","-p","secret","-s",""]
import supervisor.supervisorctl
if __name__ == '__main__':

Memmon delegates all work to the egg’s memmon Python script itself:

>>> cat('bin', 'memmon')
import supervisor.memmon
if __name__ == '__main__':

The log directory is created by the recipe:

>>> ls(sample_buildout, 'var')
d  log


  • Mustapha Benali, Author
  • Hanno Schlichting, Contributor
  • gawel, Contributor
  • aburkhalter, Contributor
File Type Py Version Uploaded on Size
collective.recipe.supervisor-0.5-py2.4.egg (md5, pgp) Python Egg 2.4 2008-08-23 15KB
collective.recipe.supervisor-0.5.tar.gz (md5, pgp) Source 2008-08-23 10KB