Circus is a process & socket manager. It can be used to monitor and control processes and sockets.
Circus can be driven via a command-line interface or programmatically through its python API.
By default Circus doesn’t secure its messages when sending information through ZeroMQ. Before running Circus, make sure you read the Security page.
To install it, check out Installing Circus
Circus’ command-line tool is configurable using an ini-style configuration file. Here is a minimal example:
[circus] check_delay = 5 endpoint = tcp://127.0.0.1:5555 [watcher:myprogram] cmd = python args = -u myprogram.py $WID warmup_delay = 0 numprocesses = 5 [watcher:anotherprogram] cmd = another_program numprocesses = 2
The file is then run using circusd:
$ circusd example.ini
If you use Circus with zc.buildout, and some of your commands are scripts generated by zc.buildout, you will need to use the copy_env and copy_path options in your watchers.
Besides processes, Circus can also bind sockets. Since every process managed by Circus is a child of the main Circus daemon, that means any program that’s controlled by Circus can use those sockets.
Running a socket is as simple as adding a socket section in the config file:
[socket:mysocket] host = localhost port = 8080
To learn more about sockets, see Circus Sockets.
To understand why it’s a killer feature, read Circus stack v.s. Classical stack.
Circus provides two command-line tools to manage your running daemon:
To learn more about these, see Command-line tools
Circus also offers a small web application that can connect to a running Circus daemon and let you monitor and interact with it.
Running the web application is as simple as adding an httpd option in the ini file:
[circus] httpd = True
Or if you want, you can run it as a standalone process with:
By default, circushttpd runs on the 8080 port.
To learn more about this feature, see The Web Console
Circus provides high-level classes and functions that will let you manage processes in your own applications.
For example, if you want to run four processes forever, you could write:
from circus import get_arbiter arbiter = get_arbiter("myprogram", 4) try: arbiter.start() finally: arbiter.stop()
This snippet will run four instances of myprogram and watch them for you, restarting them if they die unexpectedly.
To learn more about this, see Circus Library
It’s easy to extend Circus to create a more complex system, by listening to all the circusd events via its pub/sub channel, and driving it via commands.
That’s how the flapping feature works for instance: it listens to all the processes dying, measures how often it happens, and stops the incriminated watchers after too many restarts attempts.
Circus comes with a plugin system to help you write such extensions, and a few built-in plugins you can reuse. See Plugins.
You can also have a more subtile startup and shutdown behavior by using the hooks system that will let you run arbitrary code before and after some processes are started or stopped. See Hooks.
More on contribution: Contributing to Circus.