Provided by: circus_0.12.1+dfsg-1_all 
NAME
circus - Circus Documentation [image]
Circus is a Python program which can be used to monitor and control processes and sockets.
Circus can be driven via a command-line interface, a web interface or programmatically through its python
API.
To install it and try its features check out the examples, or read the rest of this page for a quick
introduction.
RUNNING A CIRCUS DAEMON
Circus provides a command-line script call circusd that can be used to manage processes organized in one
or more watchers.
Circus' command-line tool is configurable using an ini-style configuration file.
Here's a very minimal example:
[watcher:program]
cmd = python myprogram.py
numprocesses = 5
[watcher:anotherprogram]
cmd = another_program
numprocesses = 2
The file is then passed to circusd:
$ circusd example.ini
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 sockets.
To understand why it's a killer feature, read whycircussockets.
CONTROLLING CIRCUS
Circus provides two command-line tools to manage your running daemon:
• circusctl, a management console you can use to perform actions such as adding or removing workers
• circus-top, a top-like console you can use to display the memory and cpu usage of your running Circus.
To learn more about these, see cli
Circus also offers a web dashboard that can connect to a running Circus daemon and let you monitor and
interact with it.
To learn more about this feature, see circushttpd
What now ?
If you are a developer and want to leverage Circus in your own project, write plugins or hooks, go to
fordevs.
If you are an ops and want to manage your processes using Circus, go to forops.
Contributions and Feedback
More on contributing: contribs.
Useful Links:
• There's a mailing-list for any feedback or question: http://tech.groups.yahoo.com/group/circus-dev/
• The repository and issue tracker are on GitHub : https://github.com/circus-tent/circus
• Join us on the IRC : Freenode, channel #circus-tent
Documentation index
Installing Circus
Circus is a Python package which is published on PyPI - the Python Package Index.
The simplest way to install it is to use pip, a tool for installing and managing Python packages:
$ pip install circus
Or download the archive on PyPI, extract and install it manually with:
$ python setup.py install
If you want to try out Circus, see the examples.
If you are using debian or any debian based distribution, you also can use the ppa to install circus,
it's at https://launchpad.net/~roman-imankulov/+archive/circus
zc.buildout
We provide a zc.buildout configuration, you can use it by simply running the bootstrap script, then
calling buildout:
$ python bootstrap.py
$ bin/buildout
More on Requirements
Circus works with:
• Python 2.6, 2.7, 3.2 or 3.3
•
zeromq >= 2.1.10
• The version of zeromq supported is ultimately determined by what version of pyzmq is installed
by pip during circus installation.
• Their current release supports 2.x (limited), 3.x, and 4.x ZeroMQ versions.
• Note: If you are using PyPy instead of CPython, make sure to read their installation docs as
ZeroMQ version support is not the same on PyPy.
When you install circus, the latest versions of the Python dependencies will be pulled out for you.
You can also install them manually using the pip-requirements.txt file we provide:
$ pip install -r pip-requirements.txt
If you want to run the Web console you will need to install circus-web:
$ pip install circus-web
Tutorial
Step-by-step tutorial
The examples directory in the Circus repository contains many examples to get you started, but here's a
full tutorial that gives you an overview of the features.
We're going to supervise a WSGI application.
Installation
Circus is tested on Mac OS X and Linux with the latest Python 2.6, 2.7, 3.2 and 3.3. To run a full
Circus, you will also need libzmq, libevent & virtualenv.
On Debian-based systems:
$ sudo apt-get install libzmq-dev libevent-dev python-dev python-virtualenv
Create a virtualenv and install circus, circus-web and chaussette in it
$ virtualenv /tmp/circus
$ cd /tmp/circus
$ bin/pip install circus
$ bin/pip install circus-web
$ bin/pip install chaussette
Once this is done, you'll find a plethora of commands in the local bin dir.
Usage
Chaussette comes with a default Hello world app, try to run it:
$ bin/chaussette
You should be able to visit http://localhost:8080 and see hello world.
Stop Chaussette and add a circus.ini file in the directory containing:
[circus]
statsd = 1
httpd = 1
[watcher:webapp]
cmd = bin/chaussette --fd $(circus.sockets.web)
numprocesses = 3
use_sockets = True
[socket:web]
host = 127.0.0.1
port = 9999
This config file tells Circus to bind a socket on port 9999 and run 3 chaussettes workers against it. It
also activates the Circus web dashboard and the statistics module.
Save it & run it using circusd:
$ bin/circusd --daemon circus.ini
Now visit http://127.0.0.1:9999, you should see the hello world app. The difference now is that the
socket is managed by Circus and there are several web workers that are accepting connections against it.
NOTE:
The load balancing is operated by the operating system so you're getting the same speed as any other
pre-fork web server like Apache or NGinx. Circus does not interfer with the data that goes through.
You can also visit http://localhost:8080/ and enjoy the Circus web dashboard.
Interaction
Let's use the circusctl shell while the system is running:
$ bin/circusctl
circusctl 0.7.1
circusd-stats: active
circushttpd: active
webapp: active
(circusctl)
You get into an interactive shell. Type help to get all commands:
(circusctl) help
Documented commands (type help <topic>):
========================================
add get list numprocesses quit rm start stop
decr globaloptions listen numwatchers reload set stats
dstats incr listsockets options restart signal status
Undocumented commands:
======================
EOF help
Let's try basic things. Let's list the web workers processes and add a new one:
(circusctl) list webapp
13712,13713,13714
(circusctl) incr webapp
4
(circusctl) list webapp
13712,13713,13714,13973
Congrats, you've interacted with your Circus! Get off the shell with Ctrl+D and now run circus-top:
$ bin/circus-top
This is a top-like command to watch all your processes' memory and CPU usage in real time.
Hit Ctrl+C and now let's quit Circus completely via circus-ctl:
$ bin/circusctl quit
ok
Next steps
You can plug your own WSGI application instead of Chaussette's hello world simply by pointing the
application callable.
Chaussette also comes with many backends like Gevent or Meinheld.
Read https://chaussette.readthedocs.org/ for all options.
Why should I use Circus instead of X ?
1. Circus simplifies your web stack process management
Circus knows how to manage processes and sockets, so you don't have to delegate web workers management
to a WGSI server.
See whycircussockets
2. Circus provides pub/sub and poll notifications via ZeroMQ
Circus has a pub/sub channel you can subscribe to. This channel receives all events happening in
Circus. For example, you can be notified when a process is flapping, or build a client that triggers a
warning when some processes are eating all the CPU or RAM.
These events are sent via a ZeroMQ channel, which makes it different from the stdin stream Supervisord
uses:
• Circus sends events in a fire-and-forget fashion, so there's no need to manually loop through all
listeners and maintain their states.
• Subscribers can be located on a remote host.
Circus also provides ways to get status updates via one-time polls on a req/rep channel. This means
you can get your information without having to subscribe to a stream. The cli command provided by
Circus uses this channel.
See examples.
3. Circus is (Python) developer friendly
While Circus can be driven entirely by a config file and the circusctl / circusd commands, it is easy
to reuse all or part of the system to build your own custom process watcher in Python.
Every layer of the system is isolated, so you can reuse independently:
• the process wrapper (Process)
• the processes manager (Watcher)
• the global manager that runs several processes managers (Arbiter)
• and so on…
4. Circus scales
One of the use cases of Circus is to manage thousands of processes without adding overhead -- we're
dedicated to focusing on this.
Coming from Supervisor
Supervisor is a very popular solution in the Python world and we're often asked how Circus compares with
it.
If you are coming from Supervisor, this page tries to give an overview of how the tools differ.
Differences overview
Supervisor & Circus have the same goals - they both manage processes and provide a command-line script —
respectively supervisord and circusd — that reads a configuration file, forks new processes and keep them
alive.
Circus has an extra feature: the ability to bind sockets and let the processes it manages use them. This
"pre-fork" model is used by many web servers out there, like Apache or Unicorn. Having this option in
Circus can simplify a web app stack: all processes and sockets are managed by a single tool.
Both projects provide a way to control a running daemon via another script. respectively supervisorctl
and circusctl. They also both have events and a way to subscribe to them. The main difference is the
underlying technology: Supervisor uses XML-RPC for interacting with the daemon, while Circus uses ZeroMQ.
Circus & Supervisor both have a web interface to display what's going on. Circus' is more advanced
because you can follow in real time what's going on and interact with the daemon. It uses web sockets and
is developed in a separate project (circus-web.)
There are many other subtle differences in the core design, we might list here one day… In the meantime,
you can learn more about circus internals in design.
Configuration
Both systems use an ini-like file as a configuration.
• Supervisor documentation
• Circus documentation
Here's a small example of running an application with Supervisor. In this case, the application will be
started and restarted in case it crashes
[program:example]
command=npm start
directory=/home/www/my-server/
user=www-data
autostart=true
autorestart=true
redirect_stderr=True
In Circus, the same configuration is done by:
[watcher:example]
cmd=npm start
working_dir=/home/www/my-server/
user=www-data
stderr_stream.class=StdoutStream
Notice that the stderr redirection is slightly different in Circus. The tool does not have a tail feature
like in Supervisor, but will let you hook any piece of code to deal with the incoming stream. You can
create your own stream hook (as a Class) and do whatever you want with the incoming stream. Circus
provides some built-in stream classes like StdoutStream, FileStream, WatchedFileStream, or
TimedRotatingFileStream.
Circus for Ops
WARNING:
By default, Circus doesn't secure its messages when sending information through ZeroMQ. Before running
Circus in a production environment, make sure to read the Security page.
The first step to manage a Circus daemon is to write its configuration file. See configuration. If you
are deploying a web stack, have a look at sockets.
Circus can be deployed using Python 2.6, 2.7, 3.2 or 3.3 - most deployments out there are done in 2.7. To
learn how to deploy Circus, check out deployment.
To manage a Circus daemon, you should get familiar with the list of commands you can use in circusctl.
Notice that you can have the same help online when you run circusctl as a shell.
We also provide circus-top, see cli and a nice web dashboard. see circushttpd.
Last, to get the most out of Circus, make sure to check out how to use plugins and hooks. See plugins and
hooks.
Ops documentation index
Configuration
Circus can be configured using an ini-style configuration file.
Example:
[circus]
check_delay = 5
endpoint = tcp://127.0.0.1:5555
pubsub_endpoint = tcp://127.0.0.1:5556
include = \*.more.config.ini
umask = 002
[watcher:myprogram]
cmd = python
args = -u myprogram.py $(circus.wid) $(CIRCUS.ENV.VAR)
warmup_delay = 0
numprocesses = 5
# hook
hooks.before_start = my.hooks.control_redis
# will push in test.log the stream every 300 ms
stdout_stream.class = FileStream
stdout_stream.filename = test.log
# optionally rotate the log file when it reaches 1 gb
# and save 5 copied of rotated files
stdout_stream.max_bytes = 1073741824
stdout_stream.backup_count = 5
[env:myprogram]
PATH = $PATH:/bin
CAKE = lie
[plugin:statsd]
use = circus.plugins.statsd.StatsdEmitter
host = localhost
port = 8125
sample_rate = 1.0
application_name = example
[socket:web]
host = localhost
port = 8080
circus - single section
endpoint
The ZMQ socket used to manage Circus via circusctl. (default: tcp://127.0.0.1:5555)
endpoint_owner
If set to a system username and the endpoint is an ipc socket like ipc://var/run/circusd.sock,
then ownership of the socket file will be changed to that user at startup. For more details,
see security. (default: None)
pubsub_endpoint
The ZMQ PUB/SUB socket receiving publications of events. (default: tcp://127.0.0.1:5556)
papa_endpoint
If using papa, you can specify the endpoint, such as ipc://var/run/circusd.sock. (default:
tcp://127.0.0.1:20202)
statsd If set to True, Circus runs the circusd-stats daemon. (default: False)
stats_endpoint
The ZMQ PUB/SUB socket receiving publications of stats. (default: tcp://127.0.0.1:5557)
statsd_close_outputs
If True sends the circusd-stats stdout/stderr to /dev/null. (default: False)
check_delay
The polling interval in seconds for the ZMQ socket. (default: 5)
include
List of config files to include. You can use wildcards (*) to include particular schemes for
your files. The paths are absolute or relative to the config file. (default: None)
include_dir
List of config directories. All files matching *.ini under each directory will be included. The
paths are absolute or relative to the config file. (default: None)
stream_backend
Defines the type of backend to use for the streaming. Possible values are thread or gevent.
(default: thread)
warmup_delay
The interval in seconds between two watchers start. Must be an int. (default: 0)
httpd If set to True, Circus runs the circushttpd daemon. (default: False)
httpd_host
The host ran by the circushttpd daemon. (default: localhost)
httpd_port
The port ran by the circushttpd daemon. (default: 8080)
httpd_close_outputs
If True, sends the circushttpd stdout/stderr to /dev/null. (default: False)
debug If set to True, all Circus stout/stderr daemons are redirected to circusd stdout/stderr
(default: False)
debug_gc
If set to True, circusd outputs additional log info from the garbage collector. This can be
useful in tracking down memory leaks. (default: False)
pidfile
The file that must be used to keep the daemon pid.
umask Value for umask. If not set, circusd will not attempt to modify umask.
loglevel
The loglevel that we want to see (default: INFO)
logoutput
The logoutput file where we want to log (default: - to log on stdout). You can log to a remote
syslog by using the following syntax: syslog://host:port?facility where host is your syslog
server, port is optional and facility is the syslog facility to use. If you wish to log to a
local syslog you can use syslog:///path/to/syslog/socket?facility instead.
loggerconfig
A path to an INI, JSON or YAML file to configure standard Python logging for the Arbiter. The
special value "default" uses the builtin logging configuration based on the optional loglevel
and logoutput options.
Example YAML Configuration File
version: 1
disable_existing_loggers: false
formatters:
simple:
format: '%(asctime)s - %(name)s - [%(levelname)s] %(message)s'
handlers:
logfile:
class: logging.FileHandler
filename: logoutput.txt
level: DEBUG
formatter: simple
loggers:
circus:
level: DEBUG
handlers: [logfile]
propagate: no
root:
level: DEBUG
handlers: [logfile]
watcher:NAME - as many sections as you want
NAME The name of the watcher. This name is used in circusctl
cmd The executable program to run.
args Command-line arguments to pass to the program. You can use the python format syntax here to
build the parameters. Environment variables are available, as well as the worker id and the
environment variables that you passed, if any, with the "env" parameter. See Formatting the
commands and arguments with dynamic variables for more information on this.
shell If True, the processes are run in the shell (default: False)
shell_args
Command-line arguments to pass to the shell command when shell is True. Works only for *nix
system (default: None)
working_dir
The working dir for the processes (default: None)
uid The user id or name the command should run with. (The current uid is the default).
gid The group id or name the command should run with. (The current gid is the default).
copy_env
If set to true, the local environment variables will be copied and passed to the workers when
spawning them. (Default: False)
copy_path
If set to true, sys.path is passed in the subprocess environ using PYTHONPATH. copy_env has to
be true. (Default: False)
warmup_delay
The delay (in seconds) between running processes.
autostart
If set to false, the watcher will not be started automatically when the arbiter starts. The
watcher can be started explicitly (example: circusctrl start myprogram). (Default: True)
numprocesses
The number of processes to run for this watcher.
rlimit_LIMIT
Set resource limit LIMIT for the watched processes. The config name should match the RLIMIT_*
constants (not case sensitive) listed in the Python resource module reference. For example,
the config line 'rlimit_nofile = 500' sets the maximum number of open files to 500. To set a
limit value to RLIM_INFINITY, do not set a value, like this config line: 'rlimit_nofile = '.
stderr_stream.class
A fully qualified Python class name that will be instanciated, and will receive the stderr
stream of all processes in its __call__() method.
Circus provides some stream classes you can use without prefix:
• FileStream: writes in a file and can do automatic log rotation
• WatchedFileStream: writes in a file and relies on external log rotation
• TimedRotatingFileStream: writes in a file and can do rotate at certain timed intervals.
• QueueStream: write in a memory Queue
• StdoutStream: writes in the stdout
• FancyStdoutStream: writes colored output with time prefixes in the stdout
stderr_stream.*
All options starting with stderr_stream. other than class will be passed the constructor when
creating an instance of the class defined in stderr_stream.class.
stdout_stream.class
A fully qualified Python class name that will be instanciated, and will receive the stdout
stream of all processes in its __call__() method.
Circus provides some stream classes you can use without prefix:
• FileStream: writes in a file and can do automatic log rotation
• WatchedFileStream: writes in a file and relies on external log rotation
• TimedRotatingFileStream: writes in a file and can do rotate at certain timed intervals.
• QueueStream: write in a memory Queue
• StdoutStream: writes in the stdout
• FancyStdoutStream: writes colored output with time prefixes in the stdout
stdout_stream.*
All options starting with stdout_stream. other than class will be passed the constructor when
creating an instance of the class defined in stdout_stream.class.
close_child_stdout
If set to True, the stdout stream of each process will be sent to /dev/null after the fork.
Defaults to False.
close_child_stderr
If set to True, the stderr stream of each process will be sent to /dev/null after the fork.
Defaults to False.
send_hup
If True, a process reload will be done by sending the SIGHUP signal. Defaults to False.
stop_signal
The signal to send when stopping the process. Can be specified as a number or a signal name.
Signal names are case-insensitive and can include 'SIG' or not. So valid examples include quit,
INT, SIGTERM and 3. Defaults to SIGTERM.
stop_children
When sending the stop_signal, send it to the children as well. Defaults to False.
max_retry
The number of times we attempt to start a process, before we abandon and stop the whole
watcher. Defaults to 5. Set to -1 to disable max_retry and retry indefinitely.
graceful_timeout
The number of seconds to wait for a process to terminate gracefully before killing it.
When stopping a process, we first send it a stop_signal. A worker may catch this signal to
perform clean up operations before exiting. If the worker is still active after
graceful_timeout seconds, we send it a SIGKILL signal. It is not possible to catch SIGKILL
signals so the worker will stop.
Defaults to 30s.
priority
Integer that defines a priority for the watcher. When the Arbiter do some operations on all
watchers, it will sort them with this field, from the bigger number to the smallest. Defaults
to 0.
singleton
If set to True, this watcher will have at the most one process. Defaults to False.
use_sockets
If set to True, this watcher will be able to access defined sockets via their file descriptors.
If False, all parent fds are closed when the child process is forked. Defaults to False.
max_age
If set then the process will be restarted sometime after max_age seconds. This is useful when
processes deal with pool of connectors: restarting processes improves the load balancing.
Defaults to being disabled.
max_age_variance
If max_age is set then the process will live between max_age and max_age + random(0,
max_age_variance) seconds. This avoids restarting all processes for a watcher at once. Defaults
to 30 seconds.
on_demand
If set to True, the processes will be started only after the first connection to one of the
configured sockets (see below). If a restart is needed, it will be only triggered at the next
socket event.
hooks.*
Available hooks: before_start, after_start, before_spawn, after_spawn, before_stop, after_stop,
before_signal, after_signal, extended_stats
Define callback functions that hook into the watcher startup/shutdown process.
If the hook returns False and if the hook is one of before_start, before_spawn, after_start or
after_spawn, the startup will be aborted.
If the hook is before_signal and returns False, then the corresponding signal will not be sent
(except SIGKILL which is always sent)
Notice that a hook that fails during the stopping process will not abort it.
The callback definition can be followed by a boolean flag separated by a comma. When the flag
is set to true, any error occuring in the hook will be ignored. If set to false (the default),
the hook will return False.
More on hooks.
virtualenv
When provided, points to the root of a Virtualenv directory. The watcher will scan the local
site-packages and loads its content into the execution environment. Must be used with copy_env
set to True. Defaults to None.
virtualenv_py_ver
Specifies the python version of the virtualenv (e.g "3.3"). It's usefull if circus run with
another python version (e.g "2.7") The watcher will scan the local site-packages of the
specified python version and load its content into the execution environment. Must be used with
virtualenv. Defaults to None.
respawn
If set to False, the processes handled by a watcher will not be respawned automatically. The
processes can be manually respawned with the start command. (default: True)
use_papa
Set to true to use the papa.
socket:NAME - as many sections as you want
host The host of the socket. Defaults to 'localhost'
port The port. Defaults to 8080.
family The socket family. Can be 'AF_UNIX', 'AF_INET' or 'AF_INET6'. Defaults to 'AF_INET'.
type The socket type. Can be 'SOCK_STREAM', 'SOCK_DGRAM', 'SOCK_RAW', 'SOCK_RDM' or
'SOCK_SEQPACKET'. Defaults to 'SOCK_STREAM'.
interface
When provided a network interface name like 'eth0', binds the socket to that particular device
so that only packets received from that particular interface are processed by the socket. This
can be used for example to limit which device to bind when binding on IN_ADDR_ANY (0.0.0.0) or
IN_ADDR_BROADCAST (255.255.255.255). Note that this only works for some socket types,
particularly AF_INET sockets.
path When provided a path to a file that will be used as a unix socket file. If a path is provided,
family is forced to AF_UNIX and host and port are ignored.
umask When provided, sets the umask that will be used to create an AF_UNIX socket. For example,
umask=000 will produce a socket with permission 777.
replace
When creating Unix sockets ('AF_UNIX'), an existing file may indicate a problem so the default
is to fail. Specify True to simply remove the old file if you are sure that the socket is
managed only by Circus.
so_reuseport
If set to True and SO_REUSEPORT is available on target platform, circus will create and bind
new SO_REUSEPORT socket(s) for every worker it starts which is a user of this socket(s).
use_papa
Set to true to use the papa.
Once a socket is created, the ${circus.sockets.NAME} string can be used in the command (cmd or args) of a
watcher. Circus will replace it by the FD value. The watcher must also have use_sockets set to True
otherwise the socket will have been closed and you will get errors when the watcher tries to use it.
Example:
[watcher:webworker]
cmd = chaussette --fd $(circus.sockets.webapp) chaussette.util.bench_app
use_sockets = True
[socket:webapp]
host = 127.0.0.1
port = 8888
plugin:NAME - as many sections as you want
use The fully qualified name that points to the plugin class.
anything else
Every other key found in the section is passed to the plugin constructor in the config mapping.
You can use all the watcher options, since a plugin is started like a watcher.
Circus comes with a few pre-shipped plugins but you can also extend them easily by developing your own.
env or env[:WATCHERS] - as many sections as you want
anything
The name of an environment variable to assign value to. bash style environment substitutions
are supported. for example, append /bin to PATH 'PATH = $PATH:/bin'
Section responsible for delivering environment variable to run processes.
Example:
[watcher:worker1]
cmd = ping 127.0.0.1
[watcher:worker2]
cmd = ping 127.0.0.1
[env]
CAKE = lie
The variable CAKE will propagated to all watchers defined in config file.
WATCHERS can be a comma separated list of watcher sections to apply this environment to. if multiple env
sections match a watcher, they will be combine in the order they appear in the configuration file. later
entries will take precedence.
Example:
[watcher:worker1]
cmd = ping 127.0.0.1
[watcher:worker2]
cmd = ping 127.0.0.1
[env:worker1,worker2]
PATH = /bin
[env:worker1]
PATH = $PATH
[env:worker2]
CAKE = lie
worker1 will be run with PATH = $PATH (expanded from the environment circusd was run in) worker2 will be
run with PATH = /bin and CAKE = lie
It's possible to use wildcards as well.
Example:
[watcher:worker1]
cmd = ping 127.0.0.1
[watcher:worker2]
cmd = ping 127.0.0.1
[env:worker*]
PATH = /bin
Both worker1 and worker2 will be run with PATH = /bin
Using environment variables
When writing your configuration file, you can use environment variables defined in the env section or in
os.environ itself.
You just have to use the circus.env. prefix.
Example:
[watcher:worker1]
cmd = $(circus.env.shell)
[watcher:worker2]
baz = $(circus.env.user)
bar = $(circus.env.yeah)
sup = $(circus.env.oh)
[socket:socket1]
port = $(circus.env.port)
[plugin:plugin1]
use = some.path
parameter1 = $(circus.env.plugin_param)
[env]
yeah = boo
[env:worker2]
oh = ok
If a variable is defined in several places, the most specialized value has precedence: a variable defined
in env:XXX will override a variable defined in env, which will override a variable defined in os.environ.
environment substitutions can be used in any section of the configuration in any section variable.
Formatting the commands and arguments with dynamic variables
As you may have seen, it is possible to pass some information that are computed dynamically when running
the processes. Among other things, you can get the worker id (WID) and all the options that are passed to
the Process. Additionally, it is possible to access the options passed to the Watcher which instanciated
the process.
NOTE:
The worker id is different from the process id. It's a unique value, starting at 1, which is only
unique for the watcher.
For instance, if you want to access some variables that are contained in the environment, you would need
to do it with a setting like this:
cmd = "make-me-a-coffee --sugar $(CIRCUS.ENV.SUGAR_AMOUNT)"
This works with both cmd and args.
Important:
• All variables are prefixed with circus.
• The replacement is case insensitive.
Stream configuration
Simple stream class like QueueStream and StdoutStream don't have specific attributes but some other
stream class may have some:
FileStream
filename
The file path where log will be written.
time_format
The strftime format that will be used to prefix each time with a timestamp. By default they
will be not prefixed.
i.e: %Y-%m-%d %H:%M:%S
max_bytes
The max size of the log file before a new file is started. If not provided, the file is not
rolled over.
backup_count
The number of log files that will be kept By default backup_count is null.
NOTE:
Rollover occurs whenever the current log file is nearly max_bytes in length. If backup_count is >= 1,
the system will successively create new files with the same pathname as the base file, but with
extensions ".1", ".2" etc. appended to it. For example, with a backup_count of 5 and a base file name
of "app.log", you would get "app.log", "app.log.1", "app.log.2", ... through to "app.log.5". The file
being written to is always "app.log" - when it gets filled up, it is closed and renamed to
"app.log.1", and if files "app.log.1", "app.log.2" etc. exist, then they are renamed to "app.log.2",
"app.log.3" etc. respectively.
Example:
[watcher:myprogram]
cmd = python -m myapp.server
stdout_stream.class = FileStream
stdout_stream.filename = test.log
stdout_stream.time_format = %Y-%m-%d %H:%M:%S
stdout_stream.max_bytes = 1073741824
stdout_stream.backup_count = 5
WatchedFileStream
filename
The file path where log will be written.
time_format
The strftime format that will be used to prefix each time with a timestamp. By default they
will be not prefixed.
i.e: %Y-%m-%d %H:%M:%S
NOTE:
WatchedFileStream relies on an external log rotation tool to ensure that log files don't become too
big. The output file will be monitored and if it is ever deleted or moved by the external log rotation
tool, then the output file handle will be automatically reloaded.
Example:
[watcher:myprogram]
cmd = python -m myapp.server
stdout_stream.class = WatchedFileStream
stdout_stream.filename = test.log
stdout_stream.time_format = %Y-%m-%d %H:%M:%S
TimedRotatingFileStream
filename
The file path where log will be written.
backup_count
The number of log files that will be kept By default backup_count is null.
time_format
The strftime format that will be used to prefix each time with a timestamp. By default they
will be not prefixed.
i.e: %Y-%m-%d %H:%M:%S
rotate_when
The type of interval. The list of possible values is below. Note that they are not case
sensitive.
──────────────────────────────────────
Value Type of interval
──────────────────────────────────────
'S' Seconds
──────────────────────────────────────
'M' Minutes
──────────────────────────────────────
'H' Hours
──────────────────────────────────────
'D' Days
──────────────────────────────────────
'W0'-'W6' Weekday (0=Monday)
──────────────────────────────────────
'midnight' Roll over at midnight
┌────────────┬───────────────────────┐
│ │ │
rotate_interval │ │ │
The rollover interval. │ │ │
│ │ │
NOTE: │ │ │
--
AUTHOR
Mozilla Foundation, Benoit Chesneau
0.12.1 November 30, 2015 CIRCUS(1)