XML-RPC API¶

The Supvisors XML-RPC API is an extension of the Supervisor XML-RPC API. Detailed information can be found in the Supervisor XML-RPC API Documentation.

The supvisors namespace has been added to the supervisord XML-RPC interface.

The XML-RPC system.listMethods now provides the list of methods supported for both Supervisor and Supvisors. An example is provided below.

server.supvisors.getState()

Note

In the following, the namespec refers to the full name of the process, including the application name. For example: X11:xclock, where X11 is the name of a Supervisor group and xclock is the name of a Supervisor program that is referenced in the group. In some cases, it can also refer to all the programs of the group. For example: X11:*.

Status¶

class supvisors.rpcinterface.RPCInterface(supervisord)¶

This class holds the XML-RPC extension provided by Supvisors.

get_api_version()¶

Return the version of the RPC API used by Supvisors.

@return str: the version id.

get_supvisors_state()¶

Return the state of Supvisors.

@return dict: the state of Supvisors as an integer and a string.

Key Type Description

‘statecode’ int The state of Supvisors, in [0;6].

‘statename’ str The string state of Supvisors, in ['INITIALIZATION', 'DEPLOYMENT', 'OPERATION', 'CONCILIATION', 'RESTARTING', 'SHUTTING_DOWN', 'SHUTDOWN'].

get_master_address()¶

Get the address of the Supvisors Master.

@return str: the IPv4 address or host name.

get_strategies()¶

Get the strategies applied by Supvisors:

auto-fencing, when an address becomes inactive,

in the DEPLOYMENT state, to start applications,

in the CONCILIATION state, to conciliate conflicts.

@return dict: a structure containing data about the strategies applied.

Key Type Description

‘auto-fencing’ bool The application status of the auto-fencing in Supvisors.

‘conciliation’ str The conciliation strategy applied when Supvisors is in the CONCILIATION state.

‘starting’ str The starting strategy applied when Supvisors is in the DEPLOYMENT state.

get_address_info(address_name)¶

Get information about the Supvisors instance running on the host named address_name.

@param str address_name: the address name where the Supervisor daemon is running.

@throws RPCError: with code Faults.BAD_ADDRESS if address name is unknown to Supvisors.

@return dict: a structure containing data about the Supvisors instance.

Key Type Description

‘address_name’ str The address of the Supvisors instance.

‘statecode’ int The state of the Supvisors instance, in [0;5].

‘statename’ str The string state of the Supvisors instance, in ['UNKNOWN', 'CHECKING', 'RUNNING', 'SILENT', 'ISOLATING', 'ISOLATED'].

‘remote_time’ int The date, in ms, of the last heartbeat received from the Supvisors instance, in the remote reference time.

‘local_time’ int The date, in ms, of the last heartbeat received from the Supvisors instance, in the local reference time.

‘loading’ int The sum of the expected loading of the processes running on the address, in [0;100]%.

get_all_addresses_info()¶

Get information about all Supvisors instances.

@return list(dict): a list of structures containing data about all Supvisors instances.

get_application_info(application_name)¶

Get information about an application named application_name.

@param str application_name: the name of the application.

@throws RPCError:

with code Faults.BAD_SUPVISORS_STATE if Supvisors is still in INITIALIZATION state,

with code Faults.BAD_NAME if application_name is unknown to Supvisors.

@return dict: a structure containing data about the application.

Key Type Description

‘application_name’ str The name of the application.

‘statecode’ int The state of the application, in [0;4].

‘statename’ str The string state of the application, in ['UNKNOWN', 'STOPPED', 'STARTING', 'STOPPING', 'RUNNING'].

‘major_failure’ bool True if at least one required process is not started.

‘minor_failure’ bool True if at least one optional process could not be started.

get_all_applications_info()¶

Get information about all applications managed in Supvisors.

@throws RPCError: with code Faults.BAD_SUPVISORS_STATE if Supvisors is still in INITIALIZATION state.

@return list(dict): a list of structures containing data about all applications.

get_process_info(namespec)¶

Get information about a process named namespec. It just complements supervisor.getProcessInfo by telling where the process is running.

@param str namespec: the process namespec (name, group:name, or group:*).

@throws RPCError:

with code Faults.BAD_SUPVISORS_STATE if Supvisors is still in INITIALIZATION state,

with code Faults.BAD_NAME if namespec is unknown to Supvisors.

@return list(dict): a list of structures containing data about the processes.

Key Type Description

‘application_name’ str The name of the process’ application.

‘process_name’ str The name of the process.

‘statecode’ int The state of the process, in {0, 10, 20, 30, 40, 100, 200, 1000}.

‘statename’ str The string state of the process, in ['STOPPED', 'STARTING', 'RUNNING', 'BACKOFF', 'STOPPING', 'EXITED', 'FATAL', 'UNKNOWN'].

‘addresses’ list(str) The list of all addresses where the process is running.

Note

If there is more than one element in the ‘addresses’ list, a conflict is in progress.

get_all_process_info()¶

Get information about all processes.

@throws RPCError: with code Faults.BAD_SUPVISORS_STATE if Supvisors is still in INITIALIZATION state,

@return list(dict): a list of structures containing data about the processes.

get_application_rules(application_name)¶

Get the rules used to start / stop the application named application_name.

@param str application_name: the name of the application.

@throws RPCError:

with code Faults.BAD_SUPVISORS_STATE if Supvisors is still in INITIALIZATION state,

with code Faults.BAD_NAME if application_name is unknown to Supvisors.

@return list(dict): a list of structures containing the rules.

Key Type Description

‘application_name’ str The name of the application.

‘start_sequence’ int The starting rank of the application when starting all applications, in [0;127].

‘stop_sequence’ int The stopping rank of the application when stopping all applications, in [0;127].

‘starting_failure_strategy’ str The strategy applied when a process crashes in a starting application, in ['ABORT', 'STOP', 'CONTINUE'].

‘running_failure_strategy’ str The strategy applied when a process crashes in a running application, in ['CONTINUE', 'RESTART_PROCESS', 'STOP_APPLICATION', 'RESTART_APPLICATION'].

get_process_rules(namespec)¶

Get the rules used to start / stop the process named namespec.

@param str namespec: the process namespec (name, group:name, or group:*).

@throws RPCError:

with code Faults.BAD_SUPVISORS_STATE if Supvisors is still in INITIALIZATION state,

with code Faults.BAD_NAME if namespec is unknown to Supvisors.

@return list(dict): a list of structures containing the rules.

Key Type Description

‘application_name’ str The name of the process’ application.

‘process_name’ str The name of the process.

‘addresses’ list(str) The list of all addresses where the process can be started.

‘start_sequence’ int The starting rank of the process when starting the related application, in [0;127].

‘stop_sequence’ int The stopping rank of the process when stopping the related application, in [0;127].

‘required’ bool The importance of the process in the application.

‘wait_exit’ bool True if Supvisors has to wait for the process to exit before triggering the next starting phase.

‘loading’ int The expected loading of the process when RUNNING, in [0;100]%.

‘running_failure_strategy’ str The strategy applied when a process crashes in a running application, in ['CONTINUE', 'RESTART_PROCESS', 'STOP_APPLICATION', 'RESTART_APPLICATION'].

get_conflicts()¶

Get the conflicting processes.

@throws RPCError: with code Faults.BAD_SUPVISORS_STATE if Supvisors is still in INITIALIZATION state,

@return list(dict): a list of structures containing data about the conflicting processes.

The returned structure has the same format as get_process_info(namespec).

Supvisors Control¶

class supvisors.rpcinterface.RPCInterface(supervisord)

This class holds the XML-RPC extension provided by Supvisors.

conciliate(strategy)¶

Apply the conciliation strategy only if Supvisors is in CONCILIATION state, with a USER strategy.

@param ConciliationStrategies strategy: the strategy used to conciliate.

@throws RPCError:

with code Faults.BAD_SUPVISORS_STATE if Supvisors is not in state CONCILIATION,

with code Faults.BAD_STRATEGY if strategy is unknown to Supvisors.

@return bool: True if conciliation is triggered, False when strategy is USER.

restart()¶

Stops all applications and restart Supvisors through all Supervisor daemons.

@throws RPCError: with code Faults.BAD_SUPVISORS_STATE if Supvisors is still in INITIALIZATION state.

@return bool: always True unless error.

shutdown()¶

Stops all applications and shut down Supvisors through all Supervisor daemons.

@throws RPCError: with code Faults.BAD_SUPVISORS_STATE if Supvisors is still in INITIALIZATION state.

@return bool: always True unless error.

Application Control¶

class supvisors.rpcinterface.RPCInterface(supervisord)

This class holds the XML-RPC extension provided by Supvisors.

start_application(strategy, application_name, wait=True)¶

Start the application named application_name iaw the strategy and the rules file.

@param StartingStrategies strategy: the strategy used to choose addresses.

@param str application_name: the name of the application.

@param bool wait: wait for the application to be fully started.

@throws RPCError:

with code Faults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION,

with code Faults.BAD_STRATEGY if strategy is unknown to Supvisors,

with code Faults.BAD_NAME if application_name is unknown to Supvisors,

with code Faults.ALREADY_STARTED if application is STARTING, STOPPING or RUNNING,

with code Faults.ABNORMAL_TERMINATION if application could not be started.

@return bool: always True unless error or nothing to start.

stop_application(application_name, wait=True)¶

Stop the application named application_name.

@param str application_name: the name of the application.

@param bool wait: wait for the application to be fully stopped.

@throws RPCError:

with code Faults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION or CONCILIATION,

with code Faults.BAD_NAME if application_name is unknown to Supvisors.

with code Faults.NOT_RUNNING if application is STOPPED,

@return bool: always True unless error.

restart_application(strategy, application_name, wait=True)¶

Restart the application named application_name iaw the strategy and the rules file.

@param StartingStrategies strategy: the strategy used to choose addresses.

@param str application_name: the name of the application.

@param bool wait: wait for the application to be fully restarted.

@throws RPCError:

with code Faults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION,

with code Faults.BAD_STRATEGY if strategy is unknown to Supvisors,

with code Faults.BAD_NAME if application_name is unknown to Supvisors,

with code Faults.ABNORMAL_TERMINATION if application could not be restarted.

@return bool: always True unless error.

Process Control¶

class supvisors.rpcinterface.RPCInterface(supervisord)

This class holds the XML-RPC extension provided by Supvisors.

start_args(namespec, extra_args=None, wait=True)¶

Start a local process. The behaviour is different from supervisor.startProcess as it sets the process state to FATAL instead of throwing an exception to the RPC client. This RPC makes it also possible to pass extra arguments to the program command line.

@param str namespec: the process namespec.

@param str extra_args: extra arguments to be passed to the command line of the program.

@param bool wait: wait for the process to be fully started.

@throws RPCError:

with code Faults.BAD_NAME if namespec is unknown to the local Supervisor,

with code Faults.BAD_EXTRA_ARGUMENTS if program is required or has a start sequence,

with code Faults.ALREADY_STARTED if process is RUNNING,

with code Faults.ABNORMAL_TERMINATION if process could not be started.

@return bool: always True unless error.

start_process(strategy, namespec, extra_args=None, wait=True)¶

Start a process named namespec iaw the strategy and some of the rules file. WARN: the ‘wait_exit’ rule is not considered here.

@param StartingStrategies strategy: the strategy used to choose addresses.

@param str namespec: the process namespec (name, group:name, or group:*).

@param str extra_args: extra arguments to be passed to command line.

@param bool wait: wait for the process to be fully started.

@throws RPCError:

with code Faults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION,

with code Faults.BAD_STRATEGY if strategy is unknown to Supvisors,

with code Faults.BAD_NAME if namespec is unknown to Supvisors,

with code Faults.ALREADY_STARTED if process is in a running state,

with code Faults.ABNORMAL_TERMINATION if process could not be started.

@return bool: always True unless error.

stop_process(namespec, wait=True)¶

Stop the process named namespec where it is running.

@param str namespec: the process namespec (name, group:name, or group:*).

@param bool wait: wait for process to be fully stopped.

@throws RPCError:

with code Faults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION or CONCILIATION,

with code Faults.BAD_NAME if namespec is unknown to Supvisors.

with code Faults.NOT_RUNNING if process is in a stopped state,

@return bool: always True unless error.

restart_process(strategy, namespec, wait=True)¶

Restart a process named namespec iaw the strategy and some of the rules defined in the rules file. WARN: the ‘wait_exit’ rule is not considered here.

@param StartingStrategies strategy: the strategy used to choose addresses.

@param str namespec: the process namespec (name, group:name, or group:*).

@param str extra_args: extra arguments to be passed to command line.

@param bool wait: wait for process to be fully stopped.

@throws RPCError:

with code Faults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION,

with code Faults.BAD_STRATEGY if strategy is unknown to Supvisors,

with code Faults.BAD_NAME if namespec is unknown to Supvisors,

with code Faults.ABNORMAL_TERMINATION if process could not be started.

@return bool: always True unless error.

XML-RPC Clients¶

This section explains how to use the XML-RPC API from a Python, JAVA or C++ client.

Python Client¶

There are two possibilities to perform an XML-RPC from a python client. Both methods don’t require any additional third party. However, it is assumed that the environment parameter contains the relevant HTTP configuration, as it would be set for a process spawed by Supervisor. More particularly, it is expected that the following variables are set:

SUPERVISOR_SERVER_URL: the url of the Supervisor HTTP server

(ex: http://localhost:60000), * SUPERVISOR_USERNAME: the user name for the HTTP authentication (may be empty), * SUPERVISOR_PASSWORD: the password for the HTTP authentication (may be empty).

The first is to use the getRPCInterface of the supervisor.childutils module. This is available in Supervisor but it works only for the local address.

import os
from supervisor.childutils import getRPCInterface

proxy = getRPCInterface(os.environ)
proxy.supervisor.getState()
proxy.supvisors.get_supvisors_state()

The second possibility is to use the getRPCInterface of the supvisors.rpcrequests module. This is available in Supvisors and works for all addresses with a Supervisor daemon running with the same HTTP configuration as the local one.

import os
from supvisors.rpcrequests import getRPCInterface

proxy = getRPCInterface(address, os.environ)
proxy.supervisor.getState()
proxy.supvisors.get_supvisors_state()

JAVA Client¶

There is JAVA client supervisord4j referenced in the Supervisor documentation. However, it comes with the following drawbacks, taken from the README.md of supervisord4j:

of course, it doesn’t include the Supvisors XML-RPC API,

some XML-RPC are not implemented,

some implemented XML-RPC are not tested.

Each Supvisors release includes a JAR file that contains a JAVA client. It can be downloaded from the Supvisors releases.

This classes of the org.supvisors.rpc package implement all XML-RPC of all interfaces (system, supervisor and supvisors).

It requires the following additional dependency: Apache XML-RPC. The binary JAR of Apache XML-RPC 3.1.3 is available in the MAVEN repository.

import org.supvisors.rpc.*;

// create proxy
SupervisorXmlRpcClient client = new SupervisorXmlRpcClient("10.0.0.1", 60000, "toto", "p@$$w0rd");

// Supervisor XML-RPC
SupervisorXmlRpc supervisor = new SupervisorXmlRpc(client);
System.out.println(supervisor.getState());

// Supvisors XML-RPC
SupvisorsXmlRpc supvisors = new SupvisorsXmlRpc(client);
System.out.println(supvisors.getSupvisorsState());

C++ Client¶

Not implemented yet