Skip to main content

XML-RPC API文档

要使用XML-RPC接口,请使用任何XML-RPC客户端库连接到管理程序的HTTP端口,并对其运行命令。使用Python的 xmlrpclib 客户端库执行此操作的示例如下。

import xmlrpclib
server = xmlrpclib.Server('http://localhost:9001/RPC2')

您可以通过使用 supervisor 命名空间来调用针对 supervisord 及其子进程的方法。下面提供一个例子。

server.supervisor.getState()

您可以通过使用XML-RPC system.listMethods API获取 supervisord XML-RPC接口支持的方法列表:

server.system.listMethods()

您可以通过对方法使用 system.methodHelp API查看方法的帮助:

server.system.methodHelp('supervisor.shutdown')

supervisord XML-RPC接口也支持 XML-RPC多元API

您可以通过添加新的顶级RPC接口,根据需要使用新的XML-RPC API方法扩展 supervisord 功能。见 配置XML-RPC接口工厂

注解

任何XML-RPC方法调用都可能导致故障响应。这包括由客户端导致的错误参数,以及使 supervisord 无法满足请求的任何错误。当遇到故障响应时,许多XML-RPC客户端程序将引发异常。

状态和控制

class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)
getAPIVersion()

返回supervisord使用的RPC API的版本

@return字符串版本版本号

此API与Supervisor本身单独版本化。 getAPIVersion 返回的API版本仅在API更改时更改。其目的是帮助客户端识别它正在与哪个版本的Supervisor API通信。

当编写与此API通信的软件时,强烈建议您在进行方法调用之前首先测试API版本的兼容性。

注解

getAPIVersion 方法替换在3.0a1之前的Supervisor版本中找到的 getVersion。它是为了兼容性别名,但getVersion()已被弃用,并且在将来的版本中将从Supervisor中删除支持。

getSupervisorVersion()

返回supervisord正在使用的管理程序包的版本

@return字符串版本版本号

getIdentification()

返回supervisord的标识字符串

@return string标识字符串

该方法允许客户端识别在多个管理程序可能正在运行的环境的情况下与哪个管理程序实例通信。

标识是必须在Supervisor的配置文件中设置的字符串。此方法简单地将该值返回给客户端。

getState()

将supervisord的当前状态作为结构体返回

@return struct一个带有int statecode,string statename的结构体

这是由Supervisor维护的内部值,确定什么Supervisor认为是其当前的操作状态。

某些方法调用可以更改Supervisor的当前状态。例如,在工作站处于RUNNING状态时调用supervisor.shutdown()方法会在关闭时将Supervisor置于SHUTDOWN状态。

supervisor.getState()方法为客户端提供了一种检查管理程序状态的方法,既可用于信息目的,也可确保其打算调用的方法被允许。

返回值是一个结构体:

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

可能的返回值是:

状态码

statename

描述

2

致命

Supervisor遇到严重错误。

1

运行

Supervisor正常工作。

0

重新启动

Supervisor正在重新启动。

-1

关掉

Supervisor正在关机。

FATAL 状态报告不可恢复的错误,例如Supervisor内部错误或系统失控条件。一旦设置为 FATAL,Supervisor不能返回任何其他状态,而不重新启动。

FATAL 状态中,除了supervisor.shutdown()和supervisor.restart()之外的所有未来方法将自动失败,而不被调用,并且将引发故障 FATAL_STATE

SHUTDOWNRESTARTING 状态中,所有方法调用都被忽略,它们的可能返回值是未定义的。

getPID()

返回supervisord的PID

@return int PID

readLog(offset, length)

从偏移处开始读取主日志中的长度字节

@param int offset offset开始读取。 @param int length从日志中读取的字节数。 @return string result日志字节

它可以返回整个日志,从日志尾部的多个字符,或者由offset和length参数指定的日志片段:

抵消

长度

readProcessLog 的行为

不为零

错误的参数。这将引起故障 BAD_ARGUMENTS

这将返回日志的尾部,或从日志结尾处偏移的字符数。例如,如果 offset = -4和 length = 0,则最后四个字符将从日志结尾返回。

零或正

错误的参数。这将引起故障 BAD_ARGUMENTS

零或正

所有字符将从指定的 offset 返回。

零或正

将从 offset 返回多个字符长度。

如果日志为空并且请求了整个日志,则返回一个空字符串。

如果偏移或长度超出范围,将返回故障 BAD_ARGUMENTS

如果日志无法读取,则此方法将提高 NO_FILE 错误(如果文件不存在)或 FAILED 错误(如果遇到任何其他问题)。

注解

readLog()方法替换在2.1之前的Supervisor版本中找到的readMainLog()。它是为了兼容性别名,但readMainLog()已被弃用,并且在未来版本中将从Supervisor中删除支持。

clearLog()

清除主日志。

@return boolean result总是返回True除非错误

如果由于日志文件不存在而无法清除日志,则会引发故障 NO_FILE。如果由于任何其他原因无法清除日志,则会引发故障 FAILED

shutdown()

关闭Supervisor进程

@return boolean result总是返回True除非错误

此方法关闭Supervisor守护程序。如果任何进程正在运行,它们将自动被杀死,而不发出警告。

与大多数其他方法不同,如果Supervisor处于 FATAL 状态,则此方法仍将运行。

restart()

重新启动Supervisor进程

@return boolean result总是返回True除非错误

此方法软重新启动Supervisor守护程序。如果任何进程正在运行,它们将自动被杀死,而不发出警告。请注意,Supervisor的实际UNIX进程无法重新启动;只有Supervisor的主程序循环。这具有重置管理程序的内部状态的效果。

与大多数其他方法不同,如果Supervisor处于 FATAL 状态,则此方法仍将运行。

过程控制

class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)
getProcessInfo(name)

获取名为name的进程的信息

@param string name进程的名称(或’group:name’)@return struct result包含进程数据的结构

返回值是一个结构体:

{'name':           'process name',
 'group':          'group name',
 'description':    'pid 18806, uptime 0:03:12'
 'start':          1200361776,
 'stop':           0,
 'now':            1200361812,
 'state':          1,
 'statename':      'RUNNING',
 'spawnerr':       '',
 'exitstatus':     0,
 'logfile':        '/path/to/stdout-log', # deprecated, b/c only
 'stdout_logfile': '/path/to/stdout-log',
 'stderr_logfile': '/path/to/stderr-log',
 'pid':            1}
name

进程的名称

group

进程组的名称

description

如果进程状态为运行描述的值为process_id和正常运行时间。示例“pid 18806,正常运行时间0:03:12”。如果进程状态停止,描述的值是停止时间。示例:“Jun 5 03:16 PM”。

start

进程启动时的UNIX时间戳

stop

UNIX进程上次结束时的时间戳,如果进程从未停止,则为0。

now

UNIX当前时间的时间戳,可用于计算进程正常运行时间。

state

国家代码,见 过程国

statename

state 的字符串描述,请参阅 过程国

logfile

stdout_logfile 的已弃用别名。这只是为了与为Supervisor 2.x编写的客户端兼容而提供的,并且可能会在将来删除。使用 stdout_logfile

stdout_logfile

STDOUT日志文件的绝对路径和文件名

stderr_logfile

STDOUT日志文件的绝对路径和文件名

spawnerr

生成期间发生的错误的说明,如果没有则为空字符串。

exitstatus

退出进程的状态(错误级别),如果进程仍在运行,则为0。

pid

进程的UNIX进程ID(PID),如果进程未运行,则为0。

getAllProcessInfo()

获取有关所有进程的信息

@return array result一个进程状态结果数组

每个元素包含一个结构体,并且该结构体包含与 getProcessInfo 返回的结构完全相同的元素。如果进程表为空,则返回一个空数组。

startProcess(name, wait=True)

启动进程

@param string name进程名(或 group:namegroup:*)@param boolean wait等待进程完全启动@return boolean result始终为true,除非出现错误

startAllProcesses(wait=True)

启动配置文件中列出的所有进程

@param boolean wait等待每个进程完全启动@return array result一个进程状态信息结构数组

startProcessGroup(name, wait=True)

启动名为“name”的组中的所有进程,

@param string name组名@param boolean wait等待每个进程完全启动@return array result进程状态数组struct structs

stopProcess(name, wait=True)

停止按名称命名的进程

@param string name要停止的进程的名称(或’group:name’)@param boolean wait等待进程完全停止@return boolean result始终返回True,除非出现错误

stopProcessGroup(name, wait=True)

停止名为’name’的进程组中的所有进程,

@param string name组名@param boolean wait等待每个进程完全停止@return array result进程状态数组struct structs

stopAllProcesses(wait=True)

停止进程列表中的所有进程

@param boolean wait等待每个进程完全停止@return array result一个进程状态信息结构数组

signalProcess(name, signal)

向名为name的进程发送任意UNIX信号

@param string name要发信号的进程的名称(或’group:name’)@param string signal要发送的信号,名称(’HUP’)或数字(‘1’)@return boolean

signalProcessGroup(name, signal)

向名为“name”的组中的所有进程发送信号,

@param string name组名@param string signal要发送的信号,名称(’HUP’)或数字(‘1’)@return array

signalAllProcesses(signal)

向进程列表中的所有进程发送信号

@param string signal要发送的信号,如名称(’HUP’)或数字(‘1’)@return array进程状态数组struct structs

sendProcessStdin(name, chars)

将字符串发送到进程名称的stdin。如果发送非7位数据(unicode),它在被发送到进程“stdin”之前被编码为utf-8。如果chars不是字符串或不是unicode,请提高INCORRECT_PARAMETERS。如果进程没有运行,则提高NOT_RUNNING。如果进程的stdin不能接受输入(例如它被子进程关闭),则提高NO_FILE。

@param string name要发送到的进程名(或’group:name’)@param string chars要发送到进程的字符数据@return boolean result始终返回True,除非出错

sendRemoteCommEvent(type, data)

发送将由订阅RemoteCommunicationEvent的事件侦听器子进程接收的事件。

@param string type事件标头中“类型”键的字符串@param string data事件体的数据@return boolean始终返回True,除非出现错误

reloadConfig()

重新加载配置

@return boolean result总是返回True除非错误

addProcessGroup(name)

从配置文件更新运行进程的配置。

@param string name要添加的进程组的名称@return boolean如果成功,返回true

removeProcessGroup(name)

从活动配置中删除停止的进程。

@param string name要删除的进程组的名称@return boolean result指示删除是否成功

过程日志

class supervisor.rpcinterface.SupervisorNamespaceRPCInterface(supervisord)
readProcessStdoutLog(name, offset, length)

读取从偏移处开始的名称的stdout日志的长度字节

@param string name进程的名称(或’group:name’)@param int从开始读取的偏移量offset。 @param int length从日志中读取的字节数。 @return string result日志字节

readProcessStderrLog(name, offset, length)

读取从偏移处开始的名称的stderr日志中的长度字节

@param string name进程的名称(或’group:name’)@param int从开始读取的偏移量offset。 @param int length从日志中读取的字节数。 @return string result日志字节

tailProcessStdoutLog(name, offset, length)

提供比readProcessStdoutLog()更有效的拖尾(stdout)日志的方法。使用readProcessStdoutLog()读取chunks和tailProcessStdoutLog()尾。

从(名称)的日志请求(长度)字节,从(偏移量)开始。如果总日志大小大于(offset + length),则设置溢出标志,并自动增加(offset)以将缓冲区置于日志结尾。如果小于(长度)字节可用,将返回最大可用字节数。 (偏移)返回的总是日志+1中的最后一个偏移。

@param string name进程的名称(或’group:name’)@param int offset从@param开始读取的偏移量int length要返回的最大字节数@return array result [string bytes,int offset,bool overflow]

tailProcessStderrLog(name, offset, length)

提供比readProcessStderrLog()更有效的拖尾(stderr)日志。使用readProcessStderrLog()读取chunks和tailProcessStderrLog()尾部。

从(名称)的日志请求(长度)字节,从(偏移量)开始。如果总日志大小大于(offset + length),则设置溢出标志,并自动增加(offset)以将缓冲区置于日志结尾。如果小于(长度)字节可用,将返回最大可用字节数。 (偏移)返回的总是日志+1中的最后一个偏移。

@param string name进程的名称(或’group:name’)@param int offset从@param开始读取的偏移量int length要返回的最大字节数@return array result [string bytes,int offset,bool overflow]

clearProcessLogs(name)

清除命名进程的stdout和stderr日志,然后重新打开它们。

@param string name进程的名称(或’group:name’)@return boolean result始终为True,除非出现错误

clearAllProcessLogs()

清除所有进程日志文件

@return array result进程状态信息结构数组

系统方法

class supervisor.xmlrpc.SystemNamespaceRPCInterface(namespaces)
listMethods()

返回一个列出可用方法名称的数组

@return array result可用的方法名称数组(字符串)。

methodHelp(name)

返回一个显示方法文档的字符串

@param string name方法的名称。 @return string result方法名的文档。

methodSignature(name)

以[rtype,ptype,ptype ...]形式返回描述方法签名的数组,其中rtype是方法的返回数据类型,ptypes是方法接受的方法参数顺序的参数数据类型。

@param string name方法的名称。 @return array result结果。

multicall(calls)

处理调用数组,并返回结果数组。调用应该是{‘methodName’:string,’params’:array}形式的结构体。每个结果将是包含结果值的单项数组,或者是一个{‘faultCode’:int,’faultString’:string}形式的结构。当您需要进行许多小型电话而不需要大量的往返时,这是非常有用的。

@param数组调用一个调用请求数组@return array result一个结果数组