Supervisor : All you need to know to Master Supervisor

 Mastering Supervisorctl: Your Command-Line Guide to Process Management

Supervisor is a powerful process control system for Unix-like operating systems. It allows you to monitor and control a number of processes, ensuring they stay running and are restarted automatically if they crash. This tutorial focuses entirely on supervisorctl, the command-line interface that provides you with direct and efficient control over your managed processes.

Prerequisites:

• Supervisor must be installed and configured on your Linux system.

• You should have at least one program configured within your Supervisor configuration files (typically found in /etc/supervisor/conf.d/ or /etc/supervisor/supervisord.conf).

Accessing Supervisorctl:

To start interacting with Supervisor, open your terminal and run the supervisorctl command:

sudo supervisorctl

You will then be presented with the supervisor> prompt. From here, you can execute various commands to manage your configured processes using supervisorctl.

Essential Supervisorctl Commands:

Let's explore the core commands you'll use frequently within the supervisorctl interface:

1. Getting Help within Supervisorctl:

• help: Inside the supervisor> prompt, typing help displays a list of available supervisorctl commands.

  supervisor> help
  default commands (type help <topic>):
  =====================================
  add    exit      reload  restart   start   update
  avail  getlog    reread  shutdown  status  version
  clear  maintail  remove  signal    stop

• help <command>: To get specific help on a particular supervisorctl command, type help followed by the command name.

  supervisor> help status
  status <name> (name may be all, or comma-separated list)
  Get the status of all, or named, processes

2. Reloading Configuration using Supervisorctl:

• reread: This supervisorctl command instructs the Supervisor daemon to reread its configuration files. Execute this after making any changes to your Supervisor configuration files.

  supervisor> reread
  dummyprogram: available
  mywebapp: available

  After running reread via supervisorctl, the new program definitions are recognized by Supervisor, but no changes are automatically applied to running processes.

3. Updating Configurations and Starting New Processes with Supervisorctl:

• update: The supervisorctl update command compares the current running processes with the newly reread configuration. It performs the following actions:

  • Starts any new programs defined in the configuration that are not currently running.

  • Restarts programs whose configuration has been updated (if autorestart is set to true in their configuration).

  • Removes processes that have been removed from the configuration.

  supervisor> update
  dummyprogram: added process group
  mywebapp: updated process group

  Always run supervisorctl update after supervisorctl reread to ensure your running processes align with the latest configuration.

4. Checking Process Status with Supervisorctl:

• status: Executing status within supervisorctl shows the current status of all processes managed by Supervisor.

  supervisor> status
  dummyprogram:dummy_00         RUNNING   pid 1234, uptime 0:05:23
  mywebapp:web_01              RUNNING   pid 5678, uptime 1:12:48
  mywebapp:worker_03           STOPPED   Exited too quickly (1)

  The output from supervisorctl status includes the process name, its current state, process ID (PID), and uptime.

• status <name>: To view the status of specific processes or process groups using supervisorctl, provide their names (comma-separated).

  supervisor> status mywebapp:web_01,dummyprogram
  dummyprogram:dummy_00         RUNNING   pid 1234, uptime 0:06:01
  mywebapp:web_01              RUNNING   pid 5678, uptime 1:13:26

  Wildcards can also be used with supervisorctl status to check the status of multiple processes within a group (e.g., mywebapp:*).

5. Starting Processes using Supervisorctl:

• start <name>: Use the supervisorctl start command to initiate one or more processes that are currently in a stopped state.

  supervisor> start mywebapp:worker_03
  mywebapp:worker_03: started
  supervisor> status mywebapp:worker_03
  mywebapp:worker_03           RUNNING   pid 9101, uptime 0:00:05

• start all: To start all processes managed by Supervisor that are not currently running, use supervisorctl start all.

6. Stopping Processes using Supervisorctl:

• stop <name>: The supervisorctl stop command allows you to gracefully halt one or more running processes.

  supervisor> stop mywebapp:web_01
  mywebapp:web_01: stopped
  supervisor> status mywebapp:web_01
  mywebapp:web_01              STOPPED   Jun 20 10:30 AM

• stop all: To stop all currently running processes managed by Supervisor, execute supervisorctl stop all.

7. Restarting Processes using Supervisorctl:

• restart <name>: The supervisorctl restart command provides a convenient way to stop and then immediately start one or more processes. This is useful for applying configuration changes that require a process restart.

  supervisor> restart dummyprogram
  dummyprogram: stopped
  dummyprogram: started
  supervisor> status dummyprogram
  dummyprogram:dummy_00         RUNNING   pid 1516, uptime 0:00:08

• restart all: To restart all processes managed by Supervisor, use supervisorctl restart all.

8. Signaling Processes using Supervisorctl:

• signal <signal> <name>: With supervisorctl signal, you can send specific signals to managed processes. Use signal names (e.g., SIGTERM, SIGKILL, SIGHUP) or their numerical values.

  • signal SIGTERM <name>: Sends a termination signal, allowing the process to shut down cleanly.

  • signal SIGKILL <name>: Forcefully terminates the process (use as a last resort).

  • signal SIGHUP <name>: Often instructs the application to reload its configuration.

  supervisor> signal SIGTERM mywebapp:web_01
  mywebapp:web_01: sent SIGTERM
  supervisor> status mywebapp:web_01
  mywebapp:web_01              STOPPED   Waiting for process to die

• signal <signal> all: To send a specific signal to all managed processes, use supervisorctl signal <signal> all.

9. Clearing Error States using Supervisorctl:

• clear <name>: The supervisorctl clear command resets the error state of a process that might have exited too quickly. This allows Supervisor to attempt restarting the process again (if autorestart is enabled).

  supervisor> status mywebapp:worker_03
  mywebapp:worker_03           FATAL     Exited too quickly (1)
  supervisor> clear mywebapp:worker_03
  mywebapp:worker_03: cleared
  supervisor> start mywebapp:worker_03
  mywebapp:worker_03: started

• clear all: To clear the error states of all managed processes, use supervisorctl clear all.

10. Getting Process Logs with Supervisorctl:

• getlog <name>: The supervisorctl getlog command retrieves the most recent 100 bytes of combined stdout and stderr output for the specified process.

  supervisor> getlog mywebapp:web_01
  ... (last 100 bytes of mywebapp:web_01's logs) ...

• maintail <name>: Use supervisorctl maintail to continuously display the tail of the stdout and stderr output for a process in real-time. Press Ctrl+C to stop following the logs.

  supervisor> maintail mywebapp:web_01
  ... (live output of mywebapp:web_01's logs) ...

11. Shutting Down Supervisor using Supervisorctl:

• shutdown: The supervisorctl shutdown command stops all managed processes and then shuts down the Supervisor daemon itself.

  supervisor> shutdown
  Shutting down: goodbye!

  After using supervisorctl shutdown, you will need to manually restart the supervisord service to resume process management.

12. Exiting Supervisorctl:

• exit or quit: To leave the supervisorctl interactive prompt and return to your shell, type exit or quit.

  supervisor> exit
  Bye!

Examples of Common Workflows using Supervisorctl:

• Applying configuration changes:

  sudo supervisorctl reread
  sudo supervisorctl update
  sudo supervisorctl status

  
  

• Restarting a specific web application:

  sudo supervisorctl restart mywebapp
  sudo supervisorctl status mywebapp

  
  

• Troubleshooting a failed worker process:

  sudo supervisorctl status mywebapp:worker_03
  sudo supervisorctl getlog mywebapp:worker_03
  sudo supervisorctl clear mywebapp:worker_03
  sudo supervisorctl start mywebapp:worker_03
  sudo supervisorctl status mywebapp:worker_03

  
  

Conclusion:

This tutorial has provided a comprehensive guide to using the supervisorctl command-line interface for managing processes under Supervisor. By becoming proficient with these commands, you gain direct and efficient control over your applications, enabling you to effectively monitor, start, stop, restart, and troubleshoot them directly from your terminal. Keep this guide as a reference to enhance your process management skills with supervisorctl.