Supervisor

Warnings

• breaking Supervisor 4.0.0 introduced several breaking changes for programmatic interaction via XML-RPC. This includes changes to return types (e.g., booleans instead of integers) and the removal/renaming of some API methods like `getSupervisorState` (use `getState`) and `clearAllLogFiles`.
  Fix: Review the Supervisor 4.0.0 release notes and update client code to reflect the new XML-RPC API signatures and return types. Ensure Python 3.7+ is used as Python 2.6 support was dropped.
• gotcha Installing the `supervisor` package via `pip` only installs the `supervisord` server, `supervisorctl` client, and associated Python modules. It does not automatically configure, start, or manage `supervisord` as a system service. Users often mistakenly expect `pip install` to immediately launch a daemon.
  Fix: After installation, you must manually create a `supervisord.conf` file, then typically start `supervisord` via command line, or integrate it with a system's service manager (e.g., systemd, init.d) to run it as a persistent background daemon. Refer to the official Supervisor documentation for setup instructions.
• gotcha Incorrect permissions or paths in the `supervisord.conf` file can lead to `supervisord` failing to start, manage processes, or listen for connections. Common issues include `log_file` paths, `pid_file` locations, and permissions for the `unix_http_server` socket or `inet_http_server` ports.
  Fix: Always ensure paths specified in `supervisord.conf` exist and are writable by the user `supervisord` runs as. Verify that the user running `supervisord` has appropriate permissions for managing child processes. Check `supervisord` logs (`supervisord -c /path/to/supervisord.conf -n`) for startup errors.

Install

• pip install supervisor Install Supervisor

Imports

• childutils

  from supervisor import childutils

  For utilities to interact with Supervisor from a supervised child process, e.g., for event listening.
• ServerProxy

  from xmlrpc.client import ServerProxy

  Standard Python XML-RPC client for external control of the running 'supervisord' instance. The 'supervisor' package itself doesn't export a direct client class.

Quickstart

This quickstart demonstrates how to connect to a running `supervisord` instance using the standard Python `xmlrpc.client` and retrieve process information. It requires `supervisord` to be configured with an XML-RPC interface (e.g., `inet_http_server` in `supervisord.conf`) and running. Environment variables are used for URL and credentials, falling back to localhost defaults.

import xmlrpc.client
import os

# NOTE: This assumes a 'supervisord' instance is running
# and its XML-RPC interface is accessible, e.g., on port 9001.
# You might need to configure supervisord.conf for this.
# Example: [inet_http_server]
#          port=*:9001
#          username=user
#          password=123

rpc_url = os.environ.get('SUPERVISOR_RPC_URL', 'http://localhost:9001/RPC2')
rpc_username = os.environ.get('SUPERVISOR_RPC_USERNAME', '')
rpc_password = os.environ.get('SUPERVISOR_RPC_PASSWORD', '')

if rpc_username and rpc_password:
    # Add credentials to the URL if specified
    auth_url = rpc_url.replace('http://', f'http://{rpc_username}:{rpc_password}@')
    proxy = xmlrpc.client.ServerProxy(auth_url)
else:
    proxy = xmlrpc.client.ServerProxy(rpc_url)

try:
    # Get basic information about processes
    all_processes = proxy.supervisor.getAllProcessInfo()
    print(f"Found {len(all_processes)} supervised processes:")
    for p in all_processes:
        print(f"  - Name: {p['name']}, State: {p['statename']}, PID: {p['pid']}")

    # Example: Check API version
    api_version = proxy.supervisor.getAPIVersion()
    print(f"Supervisor API Version: {api_version}")

    # Example: Stop a process (replace 'my_program' with an actual process name)
    # try:
    #     print(f"Attempting to stop 'my_program': {proxy.supervisor.stopProcess('my_program')}")
    # except xmlrpc.client.Fault as e:
    #     print(f"Error stopping process: {e}")

except ConnectionRefusedError:
    print(f"ERROR: Connection refused. Is supervisord running and its RPC interface listening on {rpc_url}?", flush=True)
except xmlrpc.client.Fault as e:
    print(f"ERROR: XML-RPC Fault: {e}", flush=True)
except Exception as e:
    print(f"An unexpected error occurred: {e}", flush=True)