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 supervisor XML-RPC interface.

The XML-RPC system.listMethods provides the list of methods supported for both Supervisor and Supvisors.

server.supvisors.getState()

Important

In the following, the namespec refers to the full name of the program, including the group name, as defined in Supervisor. For example: in X11:xclock, 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 (X11:*).

Status

class supvisors.rpcinterface.RPCInterface(supvisors: Any)

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

get_api_version()

Return the version of the RPC API used by Supvisors.

Returns:

The Supvisors version.

Return type:

str

get_supvisors_state()

Return the state and modes of Supvisors.

The Supvisors state is the FSM state and is a reflection of the Supvisors Master instance state. The Supvisors modes provide the identifiers of the Supvisors instances having starting or stopping jobs in progress.

Returns:

the state and modes of Supvisors.

Return type:

dict[str, Any]

Key	Type	Description
‘identifier’	str	The Supvisors local instance identifier (host_id:http_port).
‘nick_identifier’	str	The Supvisors local instance nick name, or a copy of the Supvisors identifier if not set.
‘now_monotonic’	float	The monotonic time, in the reference time of the local host.
‘fsm_statecode’	int	The Supvisors state, in [0;8].
‘fsm_statename’	str	The Supvisors state as string, in ['OFF', 'SYNCHRONIZATION', 'ELECTION', 'DISTRIBUTION', 'OPERATION', 'CONCILIATION', 'RESTARTING', 'SHUTTING_DOWN', 'FINAL'].
‘degraded_mode’	bool	True if Supvisors is working with missing Supvisors instances.
‘discovery_mode’	bool	True if the Supvisors discovery mode is activated.
‘starting_jobs’	list(str)	The list of Supvisors instances having starting jobs in progress.
‘stopping_jobs’	list(str)	The list of Supvisors instances having stopping jobs in progress.
‘instance_states’	dict(str,str)	The state of every Supvisors instance, as seen by the local Supvisors instance.

get_all_instances_state_modes()

Get the state and modes of all Supvisors instances.

Returns:

a structure containing state and modes about all Supvisors instances.

Return type:

list[dict[str, Any]].

get_instance_state_modes()

Get the state and modes of the Supvisors instances identified by identifier (Supvisors identifier, Supervisor identifier or Supvisors stereotype).

This method can return multiple results if a Supvisors stereotype is used as parameter.

Parameters:

identifier (str) – the identifier of the Supvisors instance where the Supervisor daemon is running.

Returns:

a structure containing information about the Supvisors instance.

Return type:

list[dict[str, Any]].

Raises:

RPCError – with code Faults.BAD_NAME if identifier is unknown to Supvisors.

Key	Type	Description
‘identifier’	str	The Supvisors instance identifier (host_id:http_port).
‘nick_identifier’	str	The Supvisors instance nick name, or a copy of the Supvisors identifier if not set.
‘now_monotonic’	float	The monotonic time, in the reference time of the local host.
‘fsm_statecode’	int	The Supvisors state, in [0;8].
‘fsm_statename’	str	The Supvisors state as string, in ['OFF', 'SYNCHRONIZATION', 'ELECTION', 'DISTRIBUTION', 'OPERATION', 'CONCILIATION', 'RESTARTING', 'SHUTTING_DOWN', 'FINAL'].
‘degraded_mode’	bool	True if Supvisors is working with missing Supvisors instances.
‘discovery_mode’	bool	True if the Supvisors discovery mode is activated.
‘starting_jobs’	bool	True if the Supvisors instance has starting jobs in progress.
‘stopping_jobs’	bool	True if the Supvisors instance has stopping jobs in progress.
‘instance_states’	dict(str,str)	The state of every Supvisors instance, as seen by the Supvisors instance.

get_master_identifier()

Get the identification of the Supvisors instance elected as Supvisors Master.

The payload returned is empty if the Supvisors Master is not set yet.

Returns:

the identifier of the Supvisors Master instance and its nickname.

Return type:

dict[str, str].

Key	Type	Description
‘identifier’	str	The Supvisors Master instance identifier (host_id:http_port).
‘nick_identifier’	str	The Supvisors Master instance nick name, or a copy of the Supvisors identifier if not set.

get_core_identifiers()

Get the identification of the Supvisors core instances.

Returns:

the identifiers of the Supvisors core instances and their nickname.

Return type:

dict[str, str].

Key	Type	Description
‘identifier’	str	The Supvisors Core instance identifier (host_id:http_port).
‘nick_identifier’	str	The Supvisors Core instance nick name, or a copy of the Supvisors identifier if not set.

get_strategies()

Get the default strategies applied by Supvisors:

• auto-fencing: Supvisors instance isolation if it becomes inactive ;

• starting: used in the DISTRIBUTION state to start applications ;

• conciliation: used in the CONCILIATION state to conciliate conflicts ;

• supvisors_failure: strategy when a Supvisors instance becomes inactive.

Returns:

a structure containing information about the strategies applied.

Return type:

dict[str, Any].

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.
‘supvisors_failure’	str	The strategy used when the initial conditions are not met anymore.
‘starting’	str	The starting strategy applied when Supvisors is in the DISTRIBUTION state.

get_network_info(identifier)

Get network information about the Supvisors instance.

Parameters:

identifier (str) – the identifier of the Supvisors instance where the Supervisor daemon is running.

Returns:

a structure containing network information about the Supvisors instance.

Return type:

list[dict[str, Any]].

Raises:

RPCError – with code Faults.BAD_NAME if identifier is unknown to Supvisors.

Key	Type	Description
‘identifier’	str	The Supvisors instance identifier (host_id:http_port).
‘nick_identifier’	str	The Supvisors instance nick name, or a copy of the Supvisors identifier if not set.
‘host_id’	str	The configured Supvisors instance host identifier.
‘http_port’	int	The configured Supervisor HTTP port.
‘stereotypes’	list(str)	The stereotypes associated with the Supvisors instance configuration.
‘network’	dict(str,any)	The network details of the Supvisors instance, with keys in ['fqdn', 'machine_id', ‘addresses’`].
‘fqdn’	str	The fully-qualified domain name of the Supvisors instance.
‘machine_id’	str	The UUID of the node where the Supvisors instance is running.
‘addresses’	dict(str,any)	The network interface details, where keys are NIC names (loopback excluded), and values are as follows.
‘nic_info’	dict(str,str)	The ioctl details of the network interface, with keys in ['nic_name', 'ipv4_address', ‘netmask’`].
‘nic_name’	str	The name of the network interface.
‘ipv4_address’	str	The IPv4 address associated with the network interface.
‘netmask’	str	The netmask associated with the network interface.
‘host_name’	str	The host name given by the socket.gethostbyaddr(ipv4_address).
‘aliases’	list(str)	The host aliases given by the socket.gethostbyaddr(ipv4_address).
‘ipv4_addresses’	list(str)	The IPv4 addresses given by the socket.gethostbyaddr(ipv4_address).

get_instance_info(identifier)

Get information about the Supvisors instances identified by identifier (Supvisors identifier, Supervisor identifier or Supvisors stereotype).

This method can return multiple results if a Supvisors stereotype is used as parameter.

Parameters:

identifier (str) – the identifier of the Supvisors instance where the Supervisor daemon is running.

Returns:

a structure containing information about the Supvisors instance.

Return type:

list[dict[str, Any]].

Raises:

RPCError – with code Faults.BAD_NAME if identifier is unknown to Supvisors.

Key	Type	Description
‘identifier’	str	The Supvisors instance identifier (host_id:http_port).
‘nick_identifier’	str	The Supervisor instance identifier, or a copy of the Supvisors identifier if not set.
‘node_name’	str	The name of the node where the Supvisors instance is running.
‘port’	int	The HTTP port of the Supvisors instance.
‘statecode’	int	The Supvisors instance state, in [0;5].
‘statename’	str	The Supvisors instance state as string, in ['STOPPED', 'CHECKING', ‘CHECKED’`, 'RUNNING', 'FAILED', 'ISOLATED'].
‘loading’	int	The sum of the expected loading of the processes running on the Supvisors instance, in [0;100]%.
‘process_failure’	bool	True if one of the local processes has crashed or has exited unexpectedly.
‘remote_sequence_counter’	int	The remote TICK counter, i.e. the number of TICK events received since the remote Supvisors instance is running.
‘remote_mtime’	float	The monotonic time received in the last heartbeat sent by the remote Supvisors instance, in seconds since the remote host started.
‘remote_time’	float	The POSIX time received in the last heartbeat sent by the remote Supvisors instance, in seconds and in the remote reference time.
‘local_sequence_counter’	int	The local TICK counter when the latest TICK was received from the remote Supvisors instance.
‘local_mtime’	float	The monotonic time when the latest TICK was received from the remote Supvisors instance, in seconds since the local host started.
‘local_time’	float	The POSIX time when the latest TICK was received from the remote Supvisors instance, in seconds and in the local reference time.

get_all_instances_info()

Get information about all Supvisors instances.

Returns:

a list of structures containing information about all Supvisors instances.

Return type:

list[dict[str, Any]]

get_application_info(application_name)

Get information about an application named application_name.

Parameters:

application_name (str) – the name of the application.

Returns:

a structure containing information about the application.

Return type:

dict[str, Any]

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is still in SYNCHRONIZATION state ; Faults.BAD_NAME if application_name is unknown to Supvisors.

Key	Type	Description
‘application_name’	str	The Application name.
‘now_monotonic’	float	The monotonic time, in the reference time of the local host.
‘statecode’	int	The Application state, in [0;4].
‘statename’	str	The Application state as string, 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.

Returns:

a list of structures containing information about all applications.

Return type:

list[dict[str, Any]]

Raises:

RPCError – with code SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is still in SYNCHRONIZATION state.

get_process_info(namespec)

Get synthetic information about a process named namespec. It gives a synthetic status, based on the process information coming from all running Supvisors instances.

Parameters:

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

Returns:

a list of structures containing information about the processes.

Return type:

list[dict[str, Any]]

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is still in SYNCHRONIZATION state ; Faults.BAD_NAME if namespec is unknown to Supvisors.

Key	Type	Description
‘application_name’	str	The Application name the process belongs to.
‘process_name’	str	The Process name.
‘now_monotonic’	float	The monotonic time, in the reference time of the local host.
‘last_event_mtime’	float	The monotonic time of the last event received for this process, in the reference time of the local host.
‘statecode’	int	The Process state, in {0, 10, 20, 30, 40, 100, 200, 1000}.
‘statename’	str	The Process state as string, in ['STOPPED', 'STARTING', 'RUNNING', 'BACKOFF', 'STOPPING', 'EXITED', 'FATAL', 'UNKNOWN'].
‘expected_exit’	bool	A status telling if the process has exited expectedly.
‘identifiers’	list(str)	The identifiers of all Supvisors instances where the process is running.
‘extra_args’	str	The extra arguments used in the command line of the process.

Hint

The ‘expected_exit’ status is an answer to the following Supervisor request:

• #763 - unexpected exit not easy to read in status or getProcessInfo

Note

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

get_all_process_info()

Get synthetic information about all processes.

Returns:

a list of structures containing information about the processes.

Return type:

list[dict[str, Any]]

Raises:

RPCError – with code SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is still in SYNCHRONIZATION state.

get_local_process_info(namespec)

Get local information about a process named namespec. It is a subset of supervisor.getProcessInfo, used by Supvisors in SYNCHRONIZATION state, and giving the extra arguments of the process.

Parameters:

namespec (str) – the process namespec (name, group:name).

Returns:

a structure containing information about the process.

Return type:

dict[str, Any]

Raises:

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

Key	Type	Description
‘group’	str	The Application name the process belongs to.
‘name’	str	The Process name.
‘state’	int	The Process state, in {0, 10, 20, 30, 40, 100, 200, 1000}.
‘start’	int	The Process start time.
‘start_monotonic’	float	The Process monotonic start time.
‘stop’	int	The Process stop time.
‘stop_monotonic’	float	The Process monotonic stop time.
‘now’	float	The Process current time.
‘now_monotonic’	float	The Process monotonic current time.
‘pid’	int	The UNIX process identifier.
‘startsecs’	int	The configured duration between process STARTING and RUNNING.
‘stopwaitsecs’	int	The configured duration in STOPPING before sending a KILL signal.
‘pid’	int	The UNIX process identifier.
‘extra_args’	str	The extra arguments used in the command line of the process.
‘disabled’	bool	A status telling if the process is disabled.
‘program_name’	str	The program name in Supervisor configuration.
‘process_index’	int	The process index in the case of a homogeneous group.
‘has_stdout’	bool	True if a stdout log file is configured in the Supervisor program.
‘has_stderr’	bool	True if a stderr log file is configured in the Supervisor program.

get_all_local_process_info()

Get information about all processes located on this Supvisors instance. It is a subset of supervisor.getProcessInfo, used by Supvisors in SYNCHRONIZATION state, and giving the extra arguments of the process.

Returns:

a list of structures containing information about the processes.

Return type:

list[dict[str, Any]]

get_inner_process_info()

Get Supvisors internal information related to the processes corresponding to namespec and declared on the Supvisors instance. Mainly used for debug purpose.

Parameters:

• identifier (str) – The identifier of the Supvisors instance where the Supervisor daemon is running.

• namespec (str) – The process namespec (name, group:name).

Returns:

A structure containing information about the process.

Return type:

list[dict[str, Any]]

Raises:

• RPCError – with code Faults.BAD_NAME if identifier is unknown to Supvisors.

• RPCError – with code Faults.BAD_NAME if namespec is unknown to Supvisors.

• RPCError – with code Faults.FAILED if no handshake has been done with identifier.

get_all_inner_process_info()

Get Supvisors internal information related to the processes declared on the Supvisors instance. Mainly used for debug purpose.

Parameters:

identifier (str) – the identifier of the Supvisors instance where the Supervisor daemon is running.

Returns:

a list of structures containing information about the processes.

Return type:

list[dict[str, Any]]

Raises:

RPCError – with code Faults.BAD_NAME if identifier is unknown to Supvisors.

get_application_rules(application_name)

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

Parameters:

application_name (str) – the name of the application.

Returns:

a structure containing the rules.

Return type:

dict[str, Any]

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is still in SYNCHRONIZATION state ; Faults.BAD_NAME if application_name is unknown to Supvisors.

Key	Type	Description
‘application_name’	str	The Application name.
‘managed’	bool	The Application managed status in Supvisors. When False, the following attributes are not provided.
‘distribution’	str	The distribution rule of the Application, in ['ALL_INSTANCES', 'SINGLE_INSTANCE', 'SINGLE_NODE'].
‘identifiers’	list(str)	The identifiers of all Supvisors instances where the non-fully distributed Application processes can be started, provided only if distribution is not ALL_INSTANCES.
‘start_sequence’	int	The Application starting rank when starting all applications, in [0;127].
‘stop_sequence’	int	The Application stopping rank when stopping all applications, in [0;127].
‘starting_strategy’	str	The strategy applied when starting Application automatically, in ['CONFIG', 'LESS_LOADED', 'MOST_LOADED', 'LOCAL', 'LESS_LOADED_NODE', 'MOST_LOADED_NODE'].
‘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', 'SHUTDOWN', 'RESTART'].
‘status_formula’	str	The operational_status formula set in the Application rule.

get_process_rules(namespec)

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

Parameters:

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

Returns:

a list of structures containing the rules.

Return type:

list[dict[str, Any]]

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is still in SYNCHRONIZATION state ; Faults.BAD_NAME if namespec is unknown to Supvisors.

Key	Type	Description
‘application_name’	str	The Application name the process belongs to.
‘process_name’	str	The Process name.
‘identifiers’	list(str)	The identifiers of all Supvisors instances where the process can be started.
‘start_sequence’	int	The Process starting rank when starting the related application, in [0;127].
‘stop_sequence’	int	The Process stopping rank 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 Process expected loading 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', 'SHUTDOWN', 'RESTART'].

get_conflicts()

Get the conflicting processes among the managed applications.

Returns:

a list of structures containing information about the conflicting processes.

Return type:

list[dict[str, Any]]

Raises:

RPCError – with code SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is still in SYNCHRONIZATION state,

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

Supvisors Control

class supvisors.rpcinterface.RPCInterface(supvisors: Any)

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

change_log_level(level_param)

Change the logger level for the local Supvisors instance. If Supvisors logger is configured as AUTO, this will impact the Supervisor logger too.

Parameters:

level_param (Union[str, int]) – the new logger level, as a string or as a value.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code Faults.INCORRECT_PARAMETERS if level_param is unknown to Supervisor.

conciliate(strategy)

Apply the conciliation strategy only if Supvisors is in CONCILIATION state and if the default conciliation strategy is USER (using other strategies would trigger an automatic behavior that wouldn’t give a chance to this XML-RPC).

Parameters:

strategy (ConciliationStrategies) – the strategy used to conciliate, as a string or as a value.

Returns:

True if conciliation is triggered, False when the conciliation strategy is USER.

Return type:

bool

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in state CONCILIATION ; Faults.INCORRECT_PARAMETERS if strategy is unknown to Supvisors.

restart_sequence()

Trigger the application starting sequence.

Parameters:

wait (bool) – if True, wait for the Supvisors Starter to complete.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in OPERATION state or if starting / stopping jobs are in progress; Faults.ABNORMAL_TERMINATION if the internal start request failed.

restart()

Stops all applications and restart Supvisors through all Supervisor daemons.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code `SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is still in state SYNCHRONIZATION or has no Master instance to perform the request.

shutdown()

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

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code `SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is still in state SYNCHRONIZATION or has no Master instance to perform the request.

Supvisors Statistics Status and Control

class supvisors.rpcinterface.RPCInterface(supvisors: Any)

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

get_statistics_status()

Get information about the statistics collection status in Supvisors:

• host_stats: True if the host statistics are collected ;

• process_stats: True if the process statistics are collected ;

• collecting_period: the minimum interval between 2 samples of the same statistics type.

Returns:

a structure containing information about the statistics collected.

Return type:

dict[str, Any]

Key	Type	Description
‘host_stats’	bool	The status of Host Statistics collection in Supvisors.
‘process_stats’	bool	The status of Process Statistics collection in Supvisors.
‘collecting_period’	float	The minimum interval between 2 samples of the same statistics type.

enable_host_statistics(enable_host)

Override the host statistics option for the local Supvisors instance.

Parameters:

enable_host (bool) – if True/False and psutil installed, enable/disable host statistics collection.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code SupvisorsFaults.NOT_INSTALLED if psutil is not installed.

enable_process_statistics(enable_process)

Override the process statistics option for the local Supvisors instance.

Parameters:

enable_process (bool) – if True/False and psutil installed, enable/disable process statistics collection.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code SupvisorsFaults.NOT_INSTALLED if psutil is not installed.

update_collecting_period(collecting_period)

Override the statistics period option for the local Supvisors instance.

Parameters:

collecting_period (float) – the minimum interval between 2 samples of the same statistics type.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code SupvisorsFaults.NOT_INSTALLED if psutil is not installed.

Application Control

class supvisors.rpcinterface.RPCInterface(supvisors: Any)

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

start_application(strategy, application_name, wait=True)

Start the Managed application named application_name iaw the strategy and the rules file. To start Unmanaged applications, use supervisor.start('group:*').

Parameters:

• strategy (StartingStrategies) – the strategy used to choose a Supvisors instance, as a string or as a value.

• application_name (str) – the name of the application.

• wait (bool) – if True, wait for the application to be fully started before returning.

Returns:

always True unless error or nothing to start.

Return type:

bool

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION ; Faults.INCORRECT_PARAMETERS if strategy is unknown to Supvisors ; Faults.BAD_NAME if application_name is unknown to Supvisors ; SupvisorsFaults.NOT_MANAGED if the application is not Managed in Supvisors ; Faults.ALREADY_STARTED if the application is STARTING, STOPPING or RUNNING ; Faults.ABNORMAL_TERMINATION if the internal start request failed ; Faults.NOT_RUNNING if application_name could not be started.

stop_application(application_name, wait=True)

Stop the Managed application named application_name. To stop Unmanaged applications, use supervisor.stop('group:*').

Parameters:

• application_name (str) – the name of the application.

• wait (bool) – if True, wait for the application to be fully stopped.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION or CONCILIATION ; Faults.BAD_NAME if application_name is unknown to Supvisors ; SupvisorsFaults.NOT_MANAGED if the application is not Managed in Supvisors ; Faults.NOT_RUNNING if application_name is already stopped ; Faults.STILL_RUNNING if application_name could not be stopped.

restart_application(strategy, application_name, wait=True)

Restart the application named application_name iaw the strategy and the rules file. To restart Unmanaged applications, use supervisor.stop('group:*'), then supervisor.start('group:*').

Parameters:

• strategy (StartingStrategies) – the strategy used to choose a Supvisors instance, as a string or as a value.

• application_name (str) – the name of the application.

• wait (bool) – if True, wait for the application to be fully restarted.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION ; Faults.INCORRECT_PARAMETERS if strategy is unknown to Supvisors ; Faults.BAD_NAME if application_name is unknown to Supvisors ; SupvisorsFaults.NOT_MANAGED if the application is not Managed in Supvisors ; Faults.ABNORMAL_TERMINATION if the internal restart request failed ; Faults.NOT_RUNNING if application_name` could not be restarted.

test_start_application(strategy, application_name)

Return a distribution prediction for a start of the Managed application named application_name iaw the strategy and the rules file.

Parameters:

• strategy (StartingStrategies) – the strategy used to choose a Supvisors instance, as a string or as a value.

• application_name (str) – the name of the application.

Returns:

a list of structures with the predicted distribution of the application processes.

Return type:

list[dict[str, Any]]

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION ; Faults.INCORRECT_PARAMETERS if strategy is unknown to Supvisors ; Faults.BAD_NAME if application_name is unknown to Supvisors ; SupvisorsFaults.NOT_MANAGED if the application is not Managed in Supvisors ; Faults.ALREADY_STARTED if the application is STARTING, STOPPING or RUNNING.

Process Control

class supvisors.rpcinterface.RPCInterface(supvisors: Any)

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

start_args(namespec, extra_args='', wait=True)

Start the process named namespec on the local Supvisors instance. 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.

Parameters:

• namespec (str) – the process namespec.

• extra_args (str) – the extra arguments to be passed to the command line of the program.

• wait (bool) – if True, wait for the process to be fully started.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code: Faults.BAD_NAME if namespec is unknown to Supvisors or Supervisor ; SupvisorsFaults.DISABLED if process is disabled ; Faults.ALREADY_STARTED if process is RUNNING ; Faults.ABNORMAL_TERMINATION if process could not be started.

start_process(strategy, namespec, extra_args='', wait=True)

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

Parameters:

• strategy (StartingStrategies) – the strategy used to choose a Supvisors instance, as a string or as a value.

• namespec (str) – the process namespec (name,``group:name``, or group:*).

• extra_args (str) – the optional extra arguments to be passed to command line.

• wait (bool) – if True, wait for the process to be fully started.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION ; Faults.INCORRECT_PARAMETERS if strategy is unknown to Supvisors ; Faults.BAD_NAME if namespec is unknown to Supvisors ; Faults.ALREADY_STARTED if process is in a running state ; Faults.ABNORMAL_TERMINATION if the internal start request failed ; Faults.NOT_RUNNING if namespec could not be started.

start_any_process(strategy, regex, extra_args='', wait=True)

Start one process among those matching the regex iaw the strategy and the rules file. WARN: the ‘wait_exit’ rule is not considered here.

Parameters:

• strategy (StartingStrategies) – the strategy used to choose a Supvisors instance, as a string or as a value.

• regex (str) – a regular expression to match process namespecs.

• extra_args (str) – the optional extra arguments to be passed to command line.

• wait (bool) – if True, wait for the process to be fully started.

Returns:

the namespec of the process started unless error.

Return type:

str

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION ; Faults.INCORRECT_PARAMETERS if strategy is unknown to Supvisors ; Faults.FAILED if no stopped process found matching regex in Supvisors ; Faults.ABNORMAL_TERMINATION if the internal start request failed ; Faults.NOT_RUNNING if namespec could not be started.

stop_process(namespec, wait=True)

Stop the process named namespec on the Supvisors instance where it is running.

Parameters:

• namespec (str) – the process namespec (name, group:name, or group:*).

• wait (bool) – if True, wait for process to be fully stopped.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION or CONCILIATION ; Faults.BAD_NAME if namespec is unknown to Supvisors ; Faults.NOT_RUNNING if namespec is already stopped ; Faults.STILL_RUNNING if namespec could not be stopped.

restart_process(strategy, namespec, extra_args='', wait=True)

Restart the process named namespec iaw the strategy and the rules defined in the rules file. Note that the process will not necessarily start in the same Supvisors instance as the starting context will be re-evaluated. WARN: the ‘wait_exit’ rule is not considered here.

Parameters:

• strategy (StartingStrategies) – the strategy used to choose a Supvisors instance, as a string or as a value.

• namespec (str) – the process namespec (name, group:name, or group:*).

• extra_args (str) – the extra arguments to be passed to the command line.

• wait (bool) – if True, wait for process to be fully restarted.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION ; Faults.INCORRECT_PARAMETERS if strategy is unknown to Supvisors ; Faults.BAD_NAME if namespec is unknown to Supvisors ; Faults.ABNORMAL_TERMINATION if the internal restart request failed ; Faults.NOT_RUNNING if namespec could not be restarted.

test_start_process(strategy, namespec)

Return a distribution prediction for starting the processes corresponding to the namspec iaw the strategy and the rules file.

Parameters:

• strategy (StartingStrategies) – the strategy used to choose a Supvisors instance, as a string or as a value.

• namespec (str) – the process namespec (name,``group:name``, or group:*).

Returns:

a list of structures with the predicted distribution of the processes.

Return type:

list[dict[str, Any]].

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION ; Faults.INCORRECT_PARAMETERS if strategy is unknown to Supvisors ; Faults.BAD_NAME if namespec is unknown to Supvisors ; Faults.ALREADY_STARTED if process is in a running state.

update_numprocs(program_name, numprocs, wait=True, lazy=False)

Update dynamically the numprocs of the program. Implementation of Supervisor issue #177 - Dynamic numproc change.

When the number of processes decreases:

• the processes in excess are immediately stopped if lazy is False ;

• the processes in excess are kept in Supervisor as long as they’re still running if lazy is True.

Parameters:

• program_name (str) – the program name, as found in the section of the Supervisor configuration files. Programs, FastCGI programs and event listeners are supported.

• numprocs (int) – the new numprocs value (must be strictly positive).

• wait (bool) – if True and the numprocs value decreases, wait for the processes in excess to be stopped.

• lazy (bool) – if True, use the lazy mode when decreasing the program numprocs.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION ; Faults.BAD_NAME if program_name is unknown to Supvisors ; Faults.INCORRECT_PARAMETERS if numprocs is not a strictly positive integer ; SupvisorsFaults.NOT_APPLICABLE if the program configuration does not support numprocs ; Faults.STILL_RUNNING if one process corresponding to program_name cannot be stopped.

Hint

This XML-RPC is the implementation of the following Supervisor request:

• #177 - Dynamic numproc change

enable(program_name, wait=True)

Enable the process, i.e. remove the disabled flag on the corresponding processes if set. This information is persisted on disk so that it is taken into account on Supervisor restart. Implementation of Supervisor issue #591 - New Feature: disable/enable.

Parameters:

• program_name (str) – the name of the program

• wait (bool) – if True, wait for the corresponding processes to be fully stopped.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION ; Faults.BAD_NAME if program_name is unknown to Supvisors.

Hint

This XML-RPC is a part of the implementation of the following Supervisor request:

• #591 - New Feature: disable/enable

disable(program_name, wait=True)

Disable the program, i.e. stop the corresponding processes if necessary and prevent them to start. This information is persisted on disk so that it is taken into account on Supervisor restart. Implementation of Supervisor issue #591 - New Feature: disable/enable.

Parameters:

• program_name (str) – the name of the program

• wait (bool) – if True, wait for the corresponding processes to be fully stopped.

Returns:

always True unless error.

Return type:

bool

Raises:

RPCError – with code: SupvisorsFaults.BAD_SUPVISORS_STATE if Supvisors is not in state OPERATION ; Faults.BAD_NAME if program_name is unknown to Supvisors ; Faults.STILL_RUNNING if at least one process corresponding to program_name cannot be stopped.

Hint

This XML-RPC is a part of the implementation of the following Supervisor request:

• #591 - New Feature: disable/enable

XML-RPC Clients

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

Python Client

To perform an XML-RPC from a Python client, Supervisor provides the getRPCInterface function of the supervisor.childutils module.

The parameter requires a dictionary with the following variables 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 void),

• SUPERVISOR_PASSWORD: the password for the HTTP authentication (may be void).

If the Python client has been spawned by Supervisor, the environment already contains these parameters but they are configured to communicate with the local Supervisor instance.

>>> import os
>>> from supervisor.childutils import getRPCInterface
>>> proxy = getRPCInterface(os.environ)
>>> proxy.supvisors.get_instance_info('cliche81')
{'identifier': 'cliche81', 'node_name': 'cliche81', 'port': 60000, 'statecode': 2, 'statename': 'RUNNING',
'sequence_counter': 885, 'remote_time': 1645285505, 'local_time': 1645285505, 'loading': 24,
'fsm_statecode': 3, 'fsm_statename': 'OPERATION', 'starting_jobs': False, 'stopping_jobs': False}

If the Python client has to communicate with another Supervisor instance, the parameters must be set accordingly.

The ServerProxy of the xmlrpc module can also be used.

>>> from xmlrpc.client import ServerProxy
>>> proxy = ServerProxy('http://cliche81:60000')
>>> proxy.supvisors.get_supvisors_state()
{'fsm_statecode': 3, 'fsm_statename': 'OPERATION', 'starting_jobs': [], 'stopping_jobs': []}

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:

• some XML-RPC are not implemented,

• some implemented XML-RPC are not tested,

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

The Supvisors release comes with a JAR file including a JAVA client. It can be downloaded from the Supvisors releases.

The package org.supvisors.rpc implements all XML-RPC of all interfaces (system, supervisor and supvisors).

This package requires the following additional dependency:

• Apache XML-RPC.

The binary JAR of Apache XML-RPC 3.1.3 is available in the Apache 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());