Status and Control

class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)

getAPIVersion()

Return the version of the RPC API used by supervisord

@return string version version id

This API is versioned separately from Supervisor itself. The API versionreturned by getAPIVersion only changes when the API changes. Its purposeis to help the client identify with which version of the Supervisor API itis communicating.

When writing software that communicates with this API, it is highlyrecommended that you first test the API version for compatibility beforemaking method calls.

Note

The getAPIVersion method replaces getVersion found in Supervisorversions prior to 3.0a1. It is aliased for compatibility but getVersion()is deprecated and support will be dropped from Supervisor in a futureversion.

getSupervisorVersion()

Return the version of the supervisor package in use by supervisord

@return string version version id

getIdentification()

Return identifying string of supervisord

@return string identifier identifying string

This method allows the client to identify with which Supervisorinstance it is communicating in the case of environments wheremultiple Supervisors may be running.

The identification is a string that must be set in Supervisor’sconfiguration file. This method simply returns that value back to theclient.

getState()

Return current state of supervisord as a struct

@return struct A struct with keys int statecode, string statename

This is an internal value maintained by Supervisor that determines whatSupervisor believes to be its current operational state.

Some method calls can alter the current state of the Supervisor. Forexample, calling the method supervisor.shutdown() while the station isin the RUNNING state places the Supervisor in the SHUTDOWN state whileit is shutting down.

The supervisor.getState() method provides a means for the client to checkSupervisor’s state, both for informational purposes and to ensure that themethods it intends to call will be permitted.

The return value is a struct:

{'statecode': 1, 'statename': 'RUNNING'}

The possible return values are:

statecode	statename	Description
2	FATAL	Supervisor has experienced a serious error.
1	RUNNING	Supervisor is working normally.
0	RESTARTING	Supervisor is in the process of restarting.
-1	SHUTDOWN	Supervisor is in the process of shutting down.

The FATAL state reports unrecoverable errors, such as internalerrors inside Supervisor or system runaway conditions. Once set toFATAL, the Supervisor can never return to any other state withoutbeing restarted.

In the FATAL state, all future methods exceptsupervisor.shutdown() and supervisor.restart() will automatically failwithout being called and the fault FATAL_STATE will be raised.

In the SHUTDOWN or RESTARTING states, all method calls areignored and their possible return values are undefined.

getPID()

Return the PID of supervisord

@return int PID

readLog(offset, length)

Read length bytes from the main log starting at offset

@param int offset offset to start reading from.@param int length number of bytes to read from the log.@return string result Bytes of log

It can either return the entire log, a number of characters from thetail of the log, or a slice of the log specified by the offset andlength parameters:

Offset	Length	Behavior of readProcessLog
Negative	Not Zero	Bad arguments. This will raise the faultBAD_ARGUMENTS.
Negative	Zero	This will return the tail of the log, or offsetnumber of characters from the end of the log.For example, if offset = -4 and length= 0, then the last four characters will bereturned from the end of the log.
Zero orPositive	Negative	Bad arguments. This will raise the faultBAD_ARGUMENTS.
Zero orPositive	Zero	All characters will be returned from theoffset specified.
Zero orPositive	Positive	A number of characters length will be returnedfrom the offset.

If the log is empty and the entire log is requested, an empty stringis returned.

If either offset or length is out of range, the faultBAD_ARGUMENTS will be returned.

If the log cannot be read, this method will raise either theNO_FILE error if the file does not exist or the FAILED errorif any other problem was encountered.

Note

The readLog() method replaces readMainLog() found in Supervisorversions prior to 2.1. It is aliased for compatibility butreadMainLog() is deprecated and support will be dropped fromSupervisor in a future version.

clearLog()

Clear the main log.

@return boolean result always returns True unless error

If the log cannot be cleared because the log file does not exist, thefault NO_FILE will be raised. If the log cannot be cleared for anyother reason, the fault FAILED will be raised.

shutdown()

Shut down the supervisor process

@return boolean result always returns True unless error

This method shuts down the Supervisor daemon. If any processes are running,they are automatically killed without warning.

Unlike most other methods, if Supervisor is in the FATAL state,this method will still function.

restart()

Restart the supervisor process

@return boolean result always return True unless error

This method soft restarts the Supervisor daemon. If any processes arerunning, they are automatically killed without warning. Note that theactual UNIX process for Supervisor cannot restart; only Supervisor’smain program loop. This has the effect of resetting the internalstates of Supervisor.

Unlike most other methods, if Supervisor is in the FATAL state,this method will still function.