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 provides 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
‘fsm_statecode’
int
The Supvisors state, in [0;9].
‘fsm_statename’
str
The Supvisors state as string, in [
'OFF'
,'INITIALIZATION'
,'DISTRIBUTION'
,'OPERATION'
,'CONCILIATION'
,'RESTARTING'
,`'SHUTTING_DOWN'
,'FINAL'
].‘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.
- get_master_identifier()
Get the identification of the Supvisors instance elected as Supvisors Master.
- Returns:
the identifier of the Supvisors Master instance.
- Return type:
str
- 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.
- 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.‘starting’
str
The starting strategy applied when Supvisors is in the
DISTRIBUTION
state.
- get_instance_info(instance)
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
ifidentifier
is unknown to Supvisors.
Key
Type
Description
‘identifier’
str
The Supvisors instance identifier (
host: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;6].
‘statename’
str
The Supvisors instance state as string, in [
'UNKNOWN'
,'CHECKING'
, ‘CHECKED’`,'RUNNING'
,'SILENT'
,'ISOLATED'
].‘discovery_mode’
bool
True if the discovery mode is activated in the Supvisors instance.
‘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.
‘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.
‘fsm_statecode’
int
The Supvisors state as seen by the Supvisors instance, in [0;9].
‘fsm_statename’
str
The Supvisors state as string, in [
'OFF'
,'INITIALIZATION'
,'DISTRIBUTION'
,'OPERATION'
,'CONCILIATION'
,'RESTARTING'
,'SHUTTING_DOWN'
,'FINAL'
].‘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.
- 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 inINITIALIZATION
state ;Faults.BAD_NAME
ifapplication_name
is unknown to Supvisors.
Key
Type
Description
‘application_name’
str
The Application name.
‘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 inINITIALIZATION
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
, orgroup:*
).- 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 inINITIALIZATION
state ;Faults.BAD_NAME
ifnamespec
is unknown to Supvisors.
Key
Type
Description
‘application_name’
str
The Application name the process belongs to.
‘process_name’
str
The Process name.
‘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.
‘last_event_time’
float
The local monotonic time of the last event received for this process, in seconds.
‘identifiers’
list(str)
The deduced names of all Supvisors instances where the process is running.
‘extra_args’
str
The extra arguments used in the command line of the process.
Note
If there is more than one element in the ‘identifiers’ list, a 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 inINITIALIZATION
state.
- get_local_process_info(namespec)
Get local information about a process named
namespec
. It is a subset ofsupervisor.getProcessInfo
, used by Supvisors inINITIALIZATION
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
ifnamespec
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 date.
‘now’
float
The Process current date.
‘pid’
int
The UNIX process identifier.
‘startsecs’
int
The configured duration between process STARTING and RUNNING.
‘stopwaitsecs’
int
The configured duration between process STOPPING and STOPPED.
‘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.
- 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 inINITIALIZATION
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
ifidentifier
is unknown to Supvisors.RPCError – with code
Faults.BAD_NAME
ifnamespec
is unknown to Supvisors.RPCError – with code
Faults.FAILED
if no handshake has been done withidentifier
.
- 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
ifidentifier
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 inINITIALIZATION
state ;Faults.BAD_NAME
ifapplication_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 deduced names of all Supvisors instances where the non-fully distributed Application processes can be started, provided only if
distribution
is notALL_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
, orgroup:*
).- 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 inINITIALIZATION
state ;Faults.BAD_NAME
ifnamespec
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 deduced names 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 inINITIALIZATION
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
iflevel_param
is unknown to Supervisor.
- conciliate(strategy)
Apply the conciliation strategy only if Supvisors is in
CONCILIATION
state and if the default conciliation strategy isUSER
(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 isUSER
.- Return type:
bool
- Raises:
RPCError – with code:
SupvisorsFaults.BAD_SUPVISORS_STATE
if Supvisors is not in stateCONCILIATION
;Faults.INCORRECT_PARAMETERS
ifstrategy
is unknown to Supvisors.
- restart_sequence()
Triggers the whole starting sequence by going back to the DISTRIBUTION state.
- Parameters:
wait (bool) – if
True
, wait for Supvisors to reach the OPERATION state.- Returns:
always
True
unless error.- Return type:
bool
- Raises:
RPCError – with code
SupvisorsFaults.BAD_SUPVISORS_STATE
if Supvisors is not inOPERATION
state.
- 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 stateINITIALIZATION
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 stateINITIALIZATION
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
ifpsutil
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
ifpsutil
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
ifpsutil
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, usesupervisor.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 stateOPERATION
;Faults.INCORRECT_PARAMETERS
ifstrategy
is unknown to Supvisors ;Faults.BAD_NAME
ifapplication_name
is unknown to Supvisors ;SupvisorsFaults.NOT_MANAGED
if the application is not Managed in Supvisors ;Faults.ALREADY_STARTED
if the application isSTARTING
,STOPPING
orRUNNING
;Faults.ABNORMAL_TERMINATION
if the internal start request failed ;Faults.NOT_RUNNING
ifapplication_name
could not be started.
- stop_application(application_name, wait=True)
Stop the Managed application named
application_name
. To stop Unmanaged applications, usesupervisor.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 stateOPERATION
orCONCILIATION
;Faults.BAD_NAME
ifapplication_name
is unknown to Supvisors ;SupvisorsFaults.NOT_MANAGED
if the application is not Managed in Supvisors ;Faults.NOT_RUNNING
ifapplication_name
is already stopped ;Faults.STILL_RUNNING
ifapplication_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, usesupervisor.stop('group:*')
, thensupervisor.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 stateOPERATION
;Faults.INCORRECT_PARAMETERS
ifstrategy
is unknown to Supvisors ;Faults.BAD_NAME
ifapplication_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 stateOPERATION
;Faults.INCORRECT_PARAMETERS
ifstrategy
is unknown to Supvisors ;Faults.BAD_NAME
ifapplication_name
is unknown to Supvisors ;SupvisorsFaults.NOT_MANAGED
if the application is not Managed in Supvisors ;Faults.ALREADY_STARTED
if the application isSTARTING
,STOPPING
orRUNNING
.
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 fromsupervisor.startProcess
as it sets the process state toFATAL
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
ifnamespec
is unknown to Supvisors or Supervisor ;SupvisorsFaults.DISABLED
if process is disabled ;Faults.ALREADY_STARTED
if process isRUNNING
;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``, orgroup:*
).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 stateOPERATION
;Faults.INCORRECT_PARAMETERS
ifstrategy
is unknown to Supvisors ;Faults.BAD_NAME
ifnamespec
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
ifnamespec
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 stateOPERATION
;Faults.INCORRECT_PARAMETERS
ifstrategy
is unknown to Supvisors ;Faults.FAILED
if no stopped process found matchingregex
in Supvisors ;Faults.ABNORMAL_TERMINATION
if the internal start request failed ;Faults.NOT_RUNNING
ifnamespec
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
, orgroup:*
).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 stateOPERATION
orCONCILIATION
;Faults.BAD_NAME
ifnamespec
is unknown to Supvisors ;Faults.NOT_RUNNING
ifnamespec
is already stopped ;Faults.STILL_RUNNING
ifnamespec
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
, orgroup:*
).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 stateOPERATION
;Faults.INCORRECT_PARAMETERS
ifstrategy
is unknown to Supvisors ;Faults.BAD_NAME
ifnamespec
is unknown to Supvisors ;Faults.ABNORMAL_TERMINATION
if the internal restart request failed ;Faults.NOT_RUNNING
ifnamespec
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``, orgroup:*
).- 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 stateOPERATION
;Faults.INCORRECT_PARAMETERS
ifstrategy
is unknown to Supvisors ;Faults.BAD_NAME
ifnamespec
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 stateOPERATION
;Faults.BAD_NAME
ifprogram_name
is unknown to Supvisors ;Faults.INCORRECT_PARAMETERS
ifnumprocs
is not a strictly positive integer ;SupvisorsFaults.NOT_APPLICABLE
if the program configuration does not support numprocs ;Faults.STILL_RUNNING
if one process corresponding toprogram_name
cannot be stopped.
- 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 stateOPERATION
;Faults.BAD_NAME
ifprogram_name
is unknown to Supvisors.
- 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 stateOPERATION
;Faults.BAD_NAME
ifprogram_name
is unknown to Supvisors ;Faults.STILL_RUNNING
if at least one process corresponding toprogram_name
cannot be stopped.
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:
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());