Supervisor

https://supervisord.org/
Admin
A process control system that allows users to monitor and control processes on UNIX-like operating...
Tokens:63,342
Snippets:1,025
Trust Score:9.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Supervisor Program Configuration Example

Source: https://supervisord.org/_sources/configuration.rst.txt

Example of a complete [program:x] section in a Supervisor configuration file, demonstrating various process control and logging options.

```ini
[program:cat]
command=/bin/cat
process_name=%(program_name)s
numprocs=1
directory=/tmp
umask=022
priority=999
autostart=true
autorestart=unexpected
startsecs=10
startretries=3
exitcodes=0
stopsignal=TERM
stopwaitsecs=10
stopasgroup=false
killasgroup=false
user=chrism
redirect_stderr=false
stdout_logfile=/a/path
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stdout_capture_maxbytes=1MB
stdout_events_enabled=false
stderr_logfile=/a/path
stderr_logfile_maxbytes=1MB
stderr_logfile_backups=10
stderr_capture_maxbytes=1MB
stderr_events_enabled=false
environment=A="1",B="2"
serverurl=AUTO
```

--------------------------------

### Supervisord Configuration Example

Source: https://supervisord.org/_sources/configuration.rst.txt

Example of a [supervisord] section in an INI configuration file. This sets up logging, process limits, user, and environment.

```ini
[supervisord]
logfile = /tmp/supervisord.log
logfile_maxbytes = 50MB
logfile_backups=10
loglevel = info
pidfile = /tmp/supervisord.pid
nodaemon = false
minfds = 1024
minprocs = 200
umask = 022
user = chrism
identifier = supervisor
directory = /tmp
nocleanup = true
childlogdir = /tmp
strip_ansi = false
environment = KEY1="value1",KEY2="value2"
```

--------------------------------

### Example Token Set for PROCESS_STATE_STARTING

Source: https://supervisord.org/_sources/events.rst.txt

This is an example of a token set body for the PROCESS_STATE_STARTING event type. It includes default keys like processname, groupname, and from_state, along with a 'tries' key specific to this event.

```text
processname:cat groupname:cat from_state:STOPPED tries:0
```

--------------------------------

### Supervisorctl Update Command Example

Source: https://supervisord.org/_sources/changes.rst.txt

Illustrates the 'update' command in supervisorctl, which applies configuration changes by stopping and starting processes.

```shell
supervisor> update
baz: stopped
baz: removed process group
gazonk: stopped
gazonk: removed process group
zegroup: added process group
quux: added process group
```

--------------------------------

### Example [unix_http_server] Section Configuration

Source: https://supervisord.org/_sources/configuration.rst.txt

Provides an example configuration for the [unix_http_server] section, which defines parameters for an HTTP server listening on a UNIX domain socket. This is used by supervisorctl to communicate with supervisord.

```ini
[unix_http_server]
file = /tmp/supervisor.sock
chmod = 0777
chown= nobody:nogroup
username = user
password = 123
```

--------------------------------

### Supervisorctl Avail Command Example

Source: https://supervisord.org/_sources/changes.rst.txt

Demonstrates the 'avail' command in supervisorctl to show available and in-use programs and groups.

```shell
supervisor> avail
bar                              in use    auto      999:999
baz                              in use    auto      999:999
foo                              in use    auto      999:999
gazonk                           in use    auto      999:999
quux                             avail     auto      999:999
```

--------------------------------

### startAllProcesses

Source: https://supervisord.org/api.html

Starts all processes listed in the configuration file.

```APIDOC
## startAllProcesses(wait=True)

### Description
Start all processes listed in the configuration file.

### Parameters
#### Path Parameters
- **wait** (boolean) - Optional - Wait for each process to be fully started. Defaults to True.

### Response
#### Success Response (200)
- **result** (array) - An array of process status info structs.
```

--------------------------------

### startProcess

Source: https://supervisord.org/api.html

Starts a specific process.

```APIDOC
## startProcess(name, wait=True)

### Description
Start a process.

### Parameters
#### Path Parameters
- **name** (string) - Required - Process name (or `group:name`, or `group:*`)
- **wait** (boolean) - Optional - Wait for process to be fully started. Defaults to True.

### Response
#### Success Response (200)
- **result** (boolean) - Always true unless an error occurs.
```

--------------------------------

### Install Supervisor Manually

Source: https://supervisord.org/_sources/installing.rst.txt

If pip is not available, download the Supervisor distribution and install it manually. This requires internet access to download dependencies.

```bash
python setup.py install
```

--------------------------------

### Install Supervisor with Pip

Source: https://supervisord.org/_sources/installing.rst.txt

Use this command to install Supervisor using pip. You may need root permissions depending on your system's Python installation. This method requires internet access.

```bash
pip install supervisor
```

--------------------------------

### Start Multiple Process Groups with supervisorctl

Source: https://supervisord.org/changes.html

You can start multiple process groups simultaneously by listing them on the same command line. This applies to start, stop, and restart commands.

```bash
start groupname1:*
groupname2:*

```

--------------------------------

### FastCGI Program Configuration

Source: https://supervisord.org/_sources/configuration.rst.txt

Example of an [fcgi-program:x] section, demonstrating socket configuration, owner, mode, and other process management options.

```ini
[fcgi-program:fcgiprogramname]
command=/usr/bin/example.fcgi
socket=unix:///var/run/supervisor/%(program_name)s.sock
socket_owner=chrism
socket_mode=0700
process_name=%(program_name)s_%(process_num)02d
numprocs=5
directory=/tmp
umask=022
priority=999
autostart=true
autorestart=unexpected
startsecs=1
startretries=3
exitcodes=0
stopsignal=QUIT
stopasgroup=false
killasgroup=false
stopwaitsecs=10
user=chrism
redirect_stderr=true
stdout_logfile=/a/path
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stdout_events_enabled=false
stderr_logfile=/a/path
stderr_logfile_maxbytes=1MB
stderr_logfile_backups=10
stderr_events_enabled=false
environment=A="1",B="2"
serverurl=AUTO
```

--------------------------------

### Supervisor Event Listener Header Example

Source: https://supervisord.org/_sources/events.rst.txt

An example of a complete header line sent by supervisord to an event listener. This line contains key-value pairs detailing the event.

```text
ver:3.0 server:supervisor serial:21 pool:listener poolserial:10 eventname:PROCESS_COMMUNICATION_STDOUT len:54
```

--------------------------------

### Start Supervisor with a Specific Configuration File

Source: https://supervisord.org/installing.html

Starts the Supervisor process, explicitly specifying the location of the configuration file using the -c flag. This is redundant if the file is named 'supervisord.conf' in the current directory, as Supervisor searches there by default.

```bash
supervisord -c supervisord.conf
```

--------------------------------

### Supervisor Include Section Configuration

Source: https://supervisord.org/_sources/configuration.rst.txt

Example of an [include] section in a Supervisor configuration file, specifying which files to include.

```ini
[include]
files=program/*.conf
```

--------------------------------

### Add numprocs_start Configuration Option

Source: https://supervisord.org/_sources/changes.rst.txt

The `numprocs_start` configuration option can now be added to `[program:x]` sections to control the initial number of processes started.

```ini
numprocs_start

```

--------------------------------

### Start Process Groups with supervisorctl

Source: https://supervisord.org/_sources/changes.rst.txt

Manage process groups using supervisorctl with start, stop, and restart commands. Supports group wildcards and mixed process name specifications.

```bash
start groupname:*
```

```bash
start groupname1:* groupname2:*
```

--------------------------------

### Get Method Help

Source: https://supervisord.org/api.html

Retrieves help information for a specific XML-RPC method.

```APIDOC
## Get Method Help

### Description
This method provides help documentation for a specified XML-RPC method.

### Method
XML-RPC call

### Endpoint
system.methodHelp

### Parameters
#### Path Parameters
- **method_name** (string) - Required - The name of the method for which to retrieve help.

### Request Example
```python
server.system.methodHelp('supervisor.shutdown')
```

### Response
#### Success Response (200)
- **help_text** (string) - The help text for the specified method.
```

--------------------------------

### Supervisorctl Status Command Example

Source: https://supervisord.org/_sources/changes.rst.txt

Demonstrates the 'status' command in supervisorctl to display the current state of managed processes and groups.

```shell
supervisor> status
bar                              RUNNING    pid 14864, uptime 18:03:42
baz                              RUNNING    pid 23260, uptime 0:10:16
foo                              RUNNING    pid 14866, uptime 18:03:42
gazonk                           RUNNING    pid 23261, uptime 0:10:16
supervisor> status
bar                              RUNNING    pid 14864, uptime 18:04:18
foo                              RUNNING    pid 14866, uptime 18:04:18
quux                             RUNNING    pid 23561, uptime 0:00:02
zegroup:baz                      RUNNING    pid 23559, uptime 0:00:02
zegroup:gazonk                   RUNNING    pid 23560, uptime 0:00:02
```

--------------------------------

### Configure memmon Event Listener

Source: https://supervisord.org/_sources/events.rst.txt

Example configuration for an event listener named 'memmon' that monitors memory and subscribes to TICK_60 events.

```ini
[eventlistener:memmon]
command=memmon -a 200MB -m bob@example.com
events=TICK_60
```

--------------------------------

### Example of Process Communication Event

Source: https://supervisord.org/_sources/logging.rst.txt

This example demonstrates how a process can emit special tags to trigger Supervisor to enter capture mode and send a PROCESS_COMMUNICATION event. The data between the BEGIN and END tags forms the payload of the event.

```text
<!--XSUPERVISOR:BEGIN-->Hello!<!--XSUPERVISOR:END-->
```

--------------------------------

### Supervisord Event Header Example

Source: https://supervisord.org/events.html

This is an example of a complete header line sent by supervisord to an event listener. It includes tokens like version, server identifier, event serial, pool information, event name, and payload length.

```text
ver:3.0 server:supervisor serial:21 pool:listener poolserial:10 eventname:PROCESS_COMMUNICATION_STDOUT len:54

```

--------------------------------

### Get help for an XML-RPC method

Source: https://supervisord.org/_sources/api.rst.txt

Obtains documentation or help text for a specific XML-RPC method, such as 'supervisor.shutdown', using the system.methodHelp API.

```python
server.system.methodHelp('supervisor.shutdown')
```

--------------------------------

### PROCESS_STATE_FATAL Event Body Example

Source: https://supervisord.org/_sources/events.rst.txt

This event type is a token set with the default key/value pairs, indicating a process has entered the FATAL state after exceeding start retries.

```text
processname:cat groupname:cat from_state:BACKOFF
```

--------------------------------

### Configure FastCGI Program with Supervisor

Source: https://supervisord.org/configuration.html

This example demonstrates a complete configuration for a FastCGI program within Supervisor. It includes settings for the command, socket, owner, mode, process management, logging, and environment variables. Ensure the socket path is accessible and the user has appropriate permissions.

```ini
[fcgi-program:fcgiprogramname]
command=/usr/bin/example.fcgi
socket=unix:///var/run/supervisor/%(program_name)s.sock
socket_owner=chrism
socket_mode=0700
process_name=%(program_name)s_%(process_num)02d
numprocs=5
directory=/tmp
umask=022
priority=999
autostart=true
autorestart=unexpected
startsecs=1
startretries=3
exitcodes=0
stopsignal=QUIT
stopasgroup=false
killasgroup=false
stopwaitsecs=10
user=chrism
redirect_stderr=true
stdout_logfile=/a/path
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stdout_events_enabled=false
stderr_logfile=/a/path
stderr_logfile_maxbytes=1MB
stderr_logfile_backups=10
stderr_events_enabled=false
environment=A="1",B="2"
serverurl=AUTO

```

--------------------------------

### Supervisord Event Payload Example

Source: https://supervisord.org/events.html

This is an example payload for a PROCESS_COMMUNICATION_STDOUT event notification. The structure of the payload is determined by the event type.

```text
processname:foo groupname:bar pid:123
This is the data that was sent between the tags

```

--------------------------------

### Example Token Set for Event Filtering

Source: https://supervisord.org/_sources/events.rst.txt

This is an example of a token set that can be used for filtering events. It demonstrates key-value pairs such as processname, groupname, and from_state.

```text
processname:cat groupname:cat from_state:STOPPED
```

--------------------------------

### Supervisor Event Payload Example (PROCESS_COMMUNICATION_STDOUT)

Source: https://supervisord.org/_sources/events.rst.txt

An example payload for a PROCESS_COMMUNICATION_STDOUT event notification. This data follows the header line and provides event-specific details.

```text
processname:foo groupname:bar pid:123
```

--------------------------------

### getAllConfigInfo

Source: https://supervisord.org/api.html

Retrieves information about all available process configurations.

```APIDOC
## getAllConfigInfo()

### Description
Get info about all available process configurations.

### Response
#### Success Response (200)
- **result** (array) - An array of process config info structs. Each struct represents a single process.
```

--------------------------------

### Start a Process Group with supervisorctl

Source: https://supervisord.org/changes.html

Use supervisorctl to start, stop, or restart entire process groups. The wildcard '*' applies to all processes within the specified group.

```bash
start groupname:*

```

--------------------------------

### Generate Supervisor Configuration File

Source: https://supervisord.org/_sources/installing.rst.txt

Run this command to print a sample Supervisor configuration file to standard output. This is the first step in creating a custom configuration.

```bash
echo_supervisord_conf
```

--------------------------------

### Configure [supervisorctl] Section

Source: https://supervisord.org/configuration.html

Sets up connection details and authentication for the supervisorctl command-line client. Use 'unix://' for socket connections or 'http://' for network connections.

```ini
[supervisorctl]
serverurl = unix:///tmp/supervisor.sock
username = chris
password = 123
prompt = mysupervisor


```

--------------------------------

### Add a Program to supervisord Configuration

Source: https://supervisord.org/_sources/running.rst.txt

This is the simplest possible program configuration, defining a program named 'foo' that runs the '/bin/cat' command when supervisord starts.

```ini
[program:foo]
command=/bin/cat
```

--------------------------------

### Connecting to Supervisord XML-RPC API (Python 2)

Source: https://supervisord.org/api.html

Example of how to establish a connection to the Supervisord XML-RPC interface using Python 2's xmlrpclib.

```APIDOC
## Connecting to Supervisord XML-RPC API (Python 2)

### Description
This snippet shows how to connect to the Supervisord XML-RPC API using Python 2.

### Method
XML-RPC client connection

### Endpoint
http://localhost:9001/RPC2

### Request Example
```python
import xmlrpclib
server = xmlrpclib.Server('http://localhost:9001/RPC2')
```

### Response
This is a connection setup and does not have a direct response in this context, but successful connection allows subsequent API calls.
```

--------------------------------

### Define a Simple Program for Supervisor

Source: https://supervisord.org/running.html

Add this stanza to your supervisord.conf file to define a basic program that Supervisor will manage. This example configures the UNIX 'cat' program.

```ini
[program:foo]
command=/bin/cat

```

--------------------------------

### Configure FastCGI Program in supervisord.conf

Source: https://supervisord.org/_sources/changes.rst.txt

Use the `[fcgi-program:name]` section to configure FastCGI programs. The `socket` parameter is required and can be a TCP or Unix socket. Substitution is supported for the `socket` parameter.

```ini
[fcgi-program:fcgi_test]
;socket=tcp://localhost:8002
socket=unix:///path/to/fcgi/socket
```

--------------------------------

### startProcessGroup

Source: https://supervisord.org/api.html

Starts all processes within a specified group.

```APIDOC
## startProcessGroup(name, wait=True)

### Description
Start all processes in the group named ‘name’.

### Parameters
#### Path Parameters
- **name** (string) - Required - The group name.
- **wait** (boolean) - Optional - Wait for each process to be fully started. Defaults to True.

### Response
#### Success Response (200)
- **result** (array) - An array of process status info structs.
```

--------------------------------

### Example of Process Communication Event Payload

Source: https://supervisord.org/logging.html

This example demonstrates the format of data that can be captured between supervisor's capture mode tags. The data between `<!--XSUPERVISOR:BEGIN-->` and `<!--XSUPERVISOR:END-->` is emitted as a `PROCESS_COMMUNICATION` event payload.

```text
<!--XSUPERVISOR:BEGIN-->Hello!<!--XSUPERVISOR:END-->


```

--------------------------------

### Use Environment Variables in Supervisor Configuration

Source: https://supervisord.org/_sources/configuration.rst.txt

Demonstrates how to use environment variables within the Supervisor configuration file using the %(ENV_X)s syntax. This allows for dynamic configuration based on the environment where supervisord is started.

```ini
[program:example]
command=/usr/bin/example --loglevel=%(ENV_LOGLEVEL)s
```

--------------------------------

### Get Supervisord State

Source: https://supervisord.org/api.html

Retrieves the current state of the Supervisord process.

```APIDOC
## Get Supervisord State

### Description
This method retrieves the current state of the Supervisord process.

### Method
XML-RPC call

### Endpoint
supervisor.getState

### Parameters
This method does not take any parameters.

### Request Example
```python
server.supervisor.getState()
```

### Response
#### Success Response (200)
- **state** (string) - The current state of Supervisord (e.g., 'RUNNING', 'STOPPED').
```

--------------------------------

### Get Supervisord PID

Source: https://supervisord.org/api.html

Returns the Process ID (PID) of the running supervisord process.

```python
supervisor.getPID()
```

--------------------------------

### Configure a TICK_60 Event Listener

Source: https://supervisord.org/events.html

Use this configuration to set up an event listener that responds to the TICK_60 event. Ensure the command is executable and the events parameter is correctly specified.

```ini
[eventlistener:memmon]
command=memmon -a 200MB -m bob@example.com
events=TICK_60

```

--------------------------------

### Get All Process Information

Source: https://supervisord.org/api.html

Retrieves information for all managed processes. Returns an array of process status structs.

--------------------------------

### methodHelp

Source: https://supervisord.org/api.html

Retrieves the documentation string for a specified method.

```APIDOC
## methodHelp

### Description
Return a string showing the method’s documentation.

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the method.

### Response
#### Success Response (200)
- **result** (string) - The documentation for the method name.
```

--------------------------------

### Get Supervisor Package Version

Source: https://supervisord.org/api.html

Returns the version of the supervisor package currently in use by the supervisord process.

```python
supervisor.getSupervisorVersion()
```
Tokens:
Raw