Mastering Supervisor: A Complete Guide to Process Monitoring and Management

1. Overview

Supervisor is a C/S architecture process monitoring and management tool; this article covers its basic usage and some advanced features to solve stability problems when deploying persistent processes.

2. Problem Scenario

In production, services such as API servers or consumer processes often need to run persistently in the background. Using nohup cmd & can fail to guarantee stability; the background task may be terminated unexpectedly, causing service interruption.

Supervisor is introduced to monitor target processes and automatically restart them when they crash, improving system stability.

3. Supervisor Introduction

Supervisor is a client/server system that allows its users to control a number of processes on UNIX‑like operating systems.

Its main feature is monitoring process status and automatically restarting on abnormal termination, with support for grouping multiple processes.

4. Deployment Process

4.1 Install Supervisor

pip install supervisor

Note: Supervisor does not support Windows.

4.2 Create Service Configuration File

echo_supervisord_conf > /etc/supervisord.conf

Key parameters include [unix_http_server], [supervisord], [supervisorctl], etc. Enable the [include] directive to load additional configuration files.

4.3 Create Application Configuration File

Assume a test project with test.py . Create supervisor-test.ini:

[program:test]
command=python -u ./test.py
directory=/root/test
redirect_stderr=true
stdout_logfile=/root/test/test.log

Link it into the service config directory:

ln ./supervisor-test.ini /etc/supervisord.d/supervisor-test.ini

4.4 Start supervisord

supervisord

Supervisor searches for configuration files in several default locations; you can also specify a custom file with -c.

4.5 Start supervisorctl Client

supervisorctl

Use status to view task states, tail -f to view logs, and other commands such as start, stop, restart, signal, update.

5. Advanced Features

5.1 Process Group Management

Define groups with [group:groupname] and list member programs via the programs field, allowing batch operations like stop groupname:.

5.2 [program:x] Parameter Details

command : command to run.

directory : working directory before executing the command.

numprocs : number of process instances (requires process_name ).

autostart : start automatically when supervisord launches (default true).

stdout_logfile , stdout_logfile_maxbytes , stdout_logfile_backups : log file handling.

redirect_stderr : redirect stderr to stdout.

[program:test]
command=python -u /root/test/test.py
directory=/root/test
stdout_logfile=/root/test/test.log
stdout_logfile_maxbytes=1KB
stdout_logfile_backups=5
redirect_stderr=true

5.3 supervisorctl Command Details

Use help to list all commands; key commands include open, reload, shutdown (service control) and status, start, stop, restart, signal, update (application control).

5.4 Application Signal Handling

Register signal handlers in the application (e.g., signal.SIGTERM) to perform cleanup before exit, and trigger the handler via supervisorctl signal 15 <em>program</em>.

import time, signal
RUN = True

def exit_handler(signum, frame):
    print(f'processing signal({signal.Signals(signum).name})')
    print('update task status')
    print('clear cache data')
    global RUN
    RUN = False

signal.signal(signal.SIGTERM, exit_handler)
while RUN:
    print(time.strftime('%Y-%m-%d %H:%M:%S'))
    time.sleep(1)
print('exited')

5.5 Visual Web Interface

Enable [inet_http_server] in /etc/supervisord.conf to access a web UI (e.g., port=0.0.0.0:9001 with authentication). Do not expose it publicly.

[inet_http_server]
port=0.0.0.0:9001
username=user
password=123

6. Simple Analysis of Auto‑Restart Mechanism

The autorestart option controls whether supervisord restarts a process after exit. Values: autorestart=unexpected (default): restart only when exit code differs from exitcodes (default 0). autorestart=true: always restart, even on normal exit. autorestart=false: never restart.

Other related options: startsecs: minimum running time to consider the start successful. startretries: number of restart attempts.

Source code shows the logic: when a process exits, supervisord checks autorestart and exitstatus to decide whether to spawn a new instance.

# simplified excerpt from supervisor.process
if state == ProcessStates.EXITED:
    if self.config.autorestart:
        if self.config.autorestart is RestartUnconditionally:
            self.spawn()
        else:  # RestartWhenExitUnexpected
            if self.exitstatus not in self.config.exitcodes:
                self.spawn()

7. Summary

Supervisor provides a robust solution for managing persistent background processes, offering configuration flexibility, process grouping, signal handling, and both CLI and web interfaces. Proper use of autorestart, startsecs, and related parameters allows fine‑grained control over automatic restarts and failure handling.