Websocket API

ZendHQ provides a websocket API that communicates using JSON-RPC.

Basic Usage

You need a websocket client, such as uswc to connect to the websocket. A number of programming languages have either native websocket support, or can provide it via libraries, extensions, or plugins.

You connect to the websocket via the ZendHQ server's IP or DNS address (for example, 127.0.0.1, localhost) and its port. The default port is 10091, custom ports are defined in the zendhqd.daemon_uri setting.

The following example uses uswc:

$ uswc ws://127.0.0.1:10091

Once connected, initialize a session, using the configured ZendHQ token:

{"id":1","method":"session.create","params":{"token":"..."}}

When successful, you receive a response indicating a session has been initialized. At this point, you can proceed to call other request methods in the API as described in the remainder of this document.

Request

A request is a remote procedure call sent by the client to the server. The request is a single JSON object that has the following members:

Member	Description
id	An identifier established by the client
method	A string containing the name of the method to be invoked
params	A structured value that holds the parameter values for the method

id

The id member contains an identifier that contains a string or a number. The server response to the request contains the same identifier.

The clients generates an identifier value for every request and the server responds with the same identifier value.

This member is required.

Note: Set the member to any value you want. We recommend starting with 1 and incrementing from there. Use unique values during a given websocket session; the values only need be unique for a given session.

method

The method member contains the name of the method to be invoked. Method names can include an optional namespace prefix separated with the period character:

[<namespace>.]<methodname>

This member is required.

params

The params member contains a structured value holding the parameter values for the method. Represent parameter values as an array (by position) or as an object (by parameter name).

This member is optional.

Response

The server responds to client requests with a response. The response is a single JSON object that has the following members:

Member	Description
id	The identifier established by the client
result	The result of the remote procedure call
error	Error object

id

The id member is the identifier established by the client and identifies the request to which the response belongs.

This member is required.

result

The result member contains the result of the remote procedure call and is determined by the method invoked on the server. This member is required on success. This member must not exist if there was an error.

error

The error member contains an error object. This member is required if there was an error. This member must not exist on success.

The error object has the following members:

Member	Description
code	A number that identifies the type of the error
message	A string describing the error
data	Optional additional information about the error

The code member can have one of the following values:

Value	Description
-32700	Failed to parse JSON
-32600	Invalid request
-32601	Requested method not found
-32602	Invalid or missing parameters
-32603	Internal server error
-32000	Invalid session
-32001	Authentication failed
-32002	Not licensed

Notification

Notifications are events sent by the server to the client. They are not related to any requests made by the client. For most of the notifications the client must first subscribe for the specific type of events.

Notifications are JSON objects with the following members:

Member	Description
event	A string identifying the event
params	A structured value that holds the parameter values for the event

event

The event member is a string that identifies the event. Event names can include an optional namespace prefix separated with the period character:

[<namespace>.]<eventname>

This member is required.

params

The params member contains a structured value holding the parameter values for the event. Represent parameter values as an array (by position) or as an object (by parameter name).

This member is optional.

Batch

The client may send several Request objects at the same time by sending a JSON array filled with Request objects.

The server responds with an array containing the corresponding Response objects, after all the batch Request objects have been processed.

The Response objects being returned from a batch may be returned in any order within the array. The client must match contexts between the set of Request objects and the resulting set of Response objects based on the id member within each object.

If the batch rpc call itself fails to be recognized as a valid JSON or as an array with at least one value, the response from the server is a single Response object.

Examples

A JSON-RPC call to create a session (namespace session, method create):

C->S {"method":"session.create","id":1}
S->C {"result":{"sid":"session1","valid_until":1622098638},"id":1}

A JSON-RPC call to create a secure session with authentication:

C->S {"method":"session.create","params":{"user":"admin","password":"1234"},"id":2}
S->C {"result":{"sid":"session2","valid_until":1622098638},"id":2}

A JSON-RPC call to restore a session with positional parameters:

C->S {"method":"session.restore","params":["sessioni2"],"id":3}
S->C {"result":{"sid": "session2"},"id":3}

A JSON-RPC call to restore the session with named parameters:

C->S {"method":"session.restore","params":{"sid":"session2"},"id":4}
S->C {"result":{"sid":"session2"},"id":4}

A JSON-RPC call to restore the session with an invalid session ID value

C->S {"method":"session.restore","params":{"sid": "session3"},"id":5}
S->C {"error":{"code":-32000,"message":"invalid session id"},"id":5}

An invalid JSON-RPC call:

C->S {"method":"coffee.make","params":{"sugar":"yes","milk":"no"},"id":6}
S->C {"error":{"code":-32601,"message":"method not found"},"id":6}

An unauthorized JSON-RPC call:

C->S {"method":"tea.make","params":{"sugar":"yes","milk":"no"},"id":7}
S->C {"error":{"code":-32604,"message":"access denied"},"id":7}

A JSON-RPC call to subscribe for events of a specific type (namespace zray, method name subscribe):

C->S {"method":"zray.subscribe","id":8}
S->C {"result":"OK","id":8}

A batch of Request objects:

C->S [{"id":9,"method":"zray.version"},{"id":10,"method":"zray.subscribe"}]
S->C [{"id":9,"result":{"major":1,"minor":2}},{"id":10,"result":"OK"}]

A notification event sent out by the server (namespace zray, event name RINIT):

S->C {"event":"zray.RINIT","params":{"request_id":67}}

Namespace "session"

The session namespace manages client sessions. You can create, destroy, and restore client sessions. Clients must authenticate using an authentication token when creating or restoring a session. The authentication token is configurable. The default token is zendphp.

Methods in this namespace do not require a valid ZendHQ license.

session.version method

Requests the generic JSON RPC API version number from the server. Changes in this version number indicate

changes in any of the other namespace API versions.

Request

Member	Description
method	Fixed string "session.version"

Response

The result member contains the following values:

Member	Description
major	The JSON RPC API major version number
minor	The JSON RPC API minor version number

Example

Client:

{"id":1,"method":"session.version"}

Server:

S->C {"id":1,"result":{"major":1,"minor":1}}

session.create method

Creates a new session for the current client. The client must not have a session associated with it.

Request

Member	Description
method	Fixed string "session.create"
params	A JSON object with method parameters

The params member must contain the following values:

Member	Description
token	The authentication token

The params member can contain the following values:

Member	Description
duration	Time in seconds how long the session is valid for Z-Ray

Use the duration member to specify how long the session is valid. This affects the usage of the session ID when activating Z-Ray requests. The default duration value is 1 day (86400 seconds)

Response

The result member contains the following values:

Member	Description
sid	The session ID of the newly created session
valid_until	UNIX time until which the session is valid
license	ZendHQ license details

The license member CAN contain the following values:

Member	Description
status	Status of the license
type	One of “trial”, “cloud”, or “subscription”
identifier	License identifier (email, order ID, etc.)
expires	UNIX timestamp when the license expires
max_nodes	Maximum number of nodes

The status member CAN have one of the following values:

Member	Description
valid	The license is valid
invalid	The license is invalid
missing	The license is missing
expired	The license has expired

Example

Client:

{"id":1,"method":"session.create","params":{"token":"zendphp"}}

Server:

{"id":1,"result":{"license":{"expires":1654732800,"identifier":"mail@mail","max_nodes":-1, 
 "status":"valid","type":"trial"},"sid":"GxV-YgAAAACgJw5tT7FLPAAAAH8","valid_until":1652430107}}

session.destroy method

Destroys the current session for the client. The client must be associated with a session created with the session.create method call. Destroyed sessions are removed permanently and cannot be restored.

Request

Member	Description
method	Fixed string "session.destroy"

Response

The result member contains the fixed string "OK".

Example

Client:

{"id":1,"method":"session.destroy"}

Server:

{"id":1,"result":"OK"}

session.restore method

Restores a session previously created with session.create method call and identified by the session ID value. The client must not have any sessions associated with it. The session being restored must exist, tha tis, not destroyed nor timed out.

Request

Member	Description
method	Fixed string "session.restore"
params	A JSON object with method parameters

The params member must contain the following values:

Member	Description
sid	The ID of the session being restored
token	The authentication token

Response

The result member contains the following values:

Member	Description
sid	The session ID of the restored session
valid_until	UNIX time until which the session is valid
license	ZendHQ license details

See session.create for the license member details.

Example

Client:

{"id":1,"method":"session.restore","params":{"token":"zendphp","sid":"O7S4YAAAAACYFLMnhBsNXgAAAIM"}}

Server:

{"id":1,"result":{"license":{"expires":1654732800,"identifier":"mail@mail","max_nodes":-1,
 "status":"valid","type":"trial"},"sid":"GxV-YgAAAACgJw5tT7FLPAAAAH8","valid_until":1652430107}}

session.id method

Queries the current session ID from the server. The client must have a session associated with it.

Request

Member	Description
method	Fixed string "session.id"

Response

The result member contains the following values:

Member	Description
sid	The session ID of the restored session
valid_until	UNIX time until which the session is valid
license	License details

See session.create for the license member details.

Example

Client:

{"id":1,"method":"session.id"}

Server:

{"id":1,"result":{"license":{"expires":1654732800,"identifier":"mail@mail","max_nodes":-1,
 "status":"valid","type":"trial"},"sid":"GxV-YgAAAACgJw5tT7FLPAAAAH8","valid_until":1652430107}}

session.namespaces method

Queries the list of all the namespaces available for the current session.

Request

Member	Description
method	Fixed string "session.namespaces"

Response

The result member contains a JSON array with JSON objects that have the following values:

Member	Description
namespace	The namespace
authorized	Authorized flag
licensed	Licensed flag

The authorized member is a JSON boolean value indicating that the current session is authorized to use the namespace, that is, the namespace requires a valid session and the current session is valid, or the namespace does not require a valid session.

The licensed member is a JSON boolean value indicating that the current session is licensed to use the namespace.

Notice that the licensed member is available only to valid sessions.

Example

Client:

{"id":1,"method":"session.namespaces"}

Server:

{"id":1,"result":[
 {"authorized":true,"licensed":true,"namespace":"conf"},
 {"authorized":true,"licensed":true,"namespace":"ct"},
 {"authorized":true,"licensed":true,"namespace":"jq"},
 {"authorized":true,"licensed":true,"namespace":"mon"},
 {"authorized":true,"licensed":true,"namespace":"session"},
 {"authorized":true,"licensed":true,"namespace":"zray"},
 {"authorized":true,"licensed":true,"namespace":"zrayh"}]}

Namespace "conf"

The conf namespace manages configuration settings. Configuration settings are a key-value database with namespaces.

The client must have a session associated with it and the ZendHQ license must be valid.

conf.get method

Retrieves the configuration value identified by a namespace and key.

Request

Member	Description
method	Fixed string "conf.get"
params	A JSON object or array of objects with method parameters

The params member contains the following values:

Member	Description
ns	The namespace
key	The key

The params member may contain an array of Request objects.

Response

The result member contains an array of configuration values. The number of value elements in the array always matches the number of requested keys.

If a configuration value is not found, then the whole request returns an error.

conf.set method

Sets the configuration value identified by a namespace and key.

Request

Member	Description
method	Fixed string "conf.set"
params	A JSON object or array of objects with method parameters

The params member contains the following values:

Member	Description
ns	The namespace
key	The key
value	The value

The params member may contain an array of requests objects. The server responds with a result only when all the requested values are set.

Response

The params member contains the following values:

Member	Description
cid	The new configuration ID value

conf.id method

Queries the current configuration ID value from the server.

Request

Member	Description
method	Fixed string "conf.id"

Response

The result member contains the following values:

Member	Description
cid	The current configuration ID value

conf.namespaces method

Queries the list of all the namespaces.

Request

Member	Description
method	Fixed string "conf.namespaces"

Response

The params member contains an array of namespace names.

conf.keys method

Queries all the keys in a namespace.

Request

Member	Description
method	Fixed string "conf.keys"
params	A json object with method parameters

The params member contains the following values:

Member	Description
ns	The namespace

Response

The params member contains an array of configuration keys in the requested namespace.

Namespace "zray"

The zray namespace manages client subscriptions to Z-Ray real-time data. Clients can subscribe to Z-Ray real-time data and unsubscribe. The client must have a session associated with it and the ZendHQ license must be valid.

zray.version method

Requests the zray namespace API version number from the server.

Request

Member	Description
method	Fixed string "zray.version"

Response

The result member contains the following values:

Member	Description
major	The Z-Ray API major version number
minor	The Z-Ray API minor version number

Example

C->S {"id":1,"method":"zray.version"}
S->C {"id":1,"result":{"major":1,"minor":2}}

zray.subscribe method

Subscribes the client to the Z-Ray real-time data notifications.

Request

Member	Description
method	Fixed string "zray.subscribe"

Response

The result member contains the fixed string "OK".

Example

C->S {"id":1,"method":"zray.subscribe"}
S->C {"id":1,"result":"OK"}

zray.unsubscribe method

Unsubscribes the client from the Z-Ray real-time data notifications.

Request

Member	Description
method	Fixed string "zray.unsubscribe"

Response

The result member contains the fixed string "OK".

Example

C->S {"id":1,"method":"zray.unsubscribe"}
S->C {"id":1,"result":"OK"}

zray.RINIT event

The zray.RINIT notification event is sent out for every request before the request is processed by PHP. The params member contains the following values:

Member	Description
request_id	A number uniquely identifying the request
time_sec	UNIX time of the request
time_usec	Microseconds of the request time
method	The request method ("GET" or "PUT")
target	The target of the request
node_name	Name of the node that processes the request
pid	Process ID of the PHP process that processes the request

Example

S->C {"event":"zray.RINIT","params":{"method":"GET","node_name":"Node #1",
    "pid":29784,"request_id":3,
    "target":"http://localhost:8080/test.php?zraytok=zbS4YAAAAADWhdgnCbk6eAAAAP8",
    "time_sec":1622631380,"time_usec":708572}}

zray.RSHUTDOWN event

The zray.RSHUTDOWN notification event is sent out for every request after the request is processed by PHP. The params member contains the following values:

Member	Description
request_id	A number uniquely identifying the request
http_response_code	The HTTP response code sent to the browser
total_time	Time it took to process the request in milliseconds
memory_usage	How much memory the request used in bytes
memory_peak_usage	How much maximum memory the request used in bytes
memory_limit	PHP memory limit in bytes

Example

S->C {"event":"zray.RSHUTDOWN","params":{"http_response_code":200,
    "memory_limit":134217728,"memory_peak_usage":424216,"memory_usage":372216,
    "request_id":3,"total_time":2.8090476989746094}}

zray.ERROR event

The zray.ERROR notification event is sent out when a PHP exception, notice, warning, or error occurs. The params member contains the following values:

Member	Description
request_id	A number uniquely identifying the request
time_sec	Time when the error occurred (UNIX time)
time_usec	The milliseconds
severity	Severity of the message (0, 1, 2, or 3)
error_type	Type of the error
error_type_str	Short description of the error type
class_name	Name of the PHP exception class if this is a PHP exception
file_name	Full name of the PHP source file
line_no	The line number if the PHP source file
code	Optional code from the PHP exception
message	The error or exception message string
stack_trace	Stack trace of the error or exception

severity

The severity member can have the following values:

Value	Description
0	PHP exceptions
1	PHP notice messages
2	PHP warning messages
3	PHP error messages

error_type

The error_type member can have the following values (may depend on the PHP version):

Value	Description
0	PHP exception
1	PHP error
2	PHP warning
4	PHP parser error
8	PHP notice
16	PHP core error
32	PHP core warning
64	PHP compile error
128	PHP compile warning
256	User error
512	User warning
1024	User notice
2048	PHP strict warning
4096	PHP recoverable error
8192	PHP deprecated warning
16384	User deprecated warning

stack_trace

The stack_trace member contains an array of frame objects with the following members:

Member	Description
frame_id	The frame ID value
function_name	Name of the function
file_name	Full name of the PHP source file
line_no	The line number if the PHP source file

Example

S->C {"event":"zray.ERROR","params":{"class_name":"Exception","code":"0",
"error_type":0,"error_type_str":"EXCEPTION","file_name":"/www/test.php",
"line_no":18,"message":"Cannot say hello to World","request_id":4,"severity":0,
"stack_trace":[{"file_name":"/www/test.php","frame_id":0,
"function_name":"MyClass::hello()","line_no":18},
{"file_name":"/www/test.php","frame_id":1,"function_name":"MyClass::sayHello()"
,"line_no":27},{"file_name":"/www/test.php","frame_id":2,"function_name":"{main}",
"line_no":41}],"time_sec":1622702758,"time_usec":337052}}

zray.FUNCTIONS event

The zray.FUNCTIONS notification event is sent out after the request and contains a list of all the PHP and user functions that were called during the request. The params member contains the following members:

Member	Description
request_id	A number uniquely identifying the request
functions	An array of functions

functions

The functions member is an array of functions objects, which contain the following members:

Member	Description
type	Type of the functions ("USER" or "INTERNAL")
function_name	Name of the function
times_called	How many times the function was called
total_duration_inclusive	Total inclusive time spent in this function in seconds
total_duration_exclusive	Total exclusive time spent in this function in seconds
file_name	Full name of the PHP source file
line_start	The line number in the PHP source file where the function starts
line_end	The line number in the PHP source file where the function ends

Example

{"event":"zray.FUNCTIONS","params":{"functions":[
    {"file_name":"/www/test.php","function_name":"{main}","line_end":55,"line_start":1,
     "times_called":1,"total_duration_exclusive":0.030755996704101562,
     "total_duration_inclusive":0.5860328674316406,"type":"USER"},
    {"file_name":"/www/test.php","function_name":"MyClass::sayHello()","line_end":32,
     "line_start":24,"times_called":3,"total_duration_exclusive":0.032901763916015625,
     "total_duration_inclusive":0.5021095275878906,"type":"USER"},
    {"file_name":"/www/test.php","function_name":"MyClass::hello()","line_end":22,
     "line_start":14,"times_called":3,"total_duration_exclusive":0.1418590545654297,
     "total_duration_inclusive":0.1437664031982422,"type":"USER"},
    {"file_name":"/www/test.php","function_name":"MyClass::__construct()","line_end":12,
     "line_start":10,"times_called":1,"total_duration_exclusive":0.0050067901611328125,
     "total_duration_inclusive":0.0050067901611328125,"type":"USER"},
    {"function_name":"Exception::getMessage()","times_called":1,
     "total_duration_exclusive":0.0030994415283203125,
     "total_duration_inclusive":0.0030994415283203125,"type":"INTERNAL"},
    {"function_name":"array_key_exists()","times_called":1,
     "total_duration_exclusive":0.0030994415283203125,
     "total_duration_inclusive":0.0030994415283203125,"type":"INTERNAL"},
    {"function_name":"Exception::__construct()","times_called":1,
     "total_duration_exclusive":0.0019073486328125,
     "total_duration_inclusive":0.0019073486328125,"type":"INTERNAL"}],"request_id":4}}

zray.STORAGE event

The zray.STORAGE notification event is sent out when a Z-Ray plugin is activated and writes plugin-specific data to the $storage array. The params member contains the following members:

Member	Description
request_id	A number uniquely identifying the request
name_space	A string identifying the Z-Ray plugin
key	The key value from the $storage array
data	A structured value holding the value(s) from the $storage variable

Example

S->C {"event":"zray.STORAGE","params":{"data":{"#":2,"Name":"Perforce"},
"key":"Params","name_space":"MyClass","request_id":4}}

zray.SUPERGLOBALS event

The zray.SUPERGLOBALS notification event is sent out with every PHP superglobal array at the end of the request. The params member contains the following members:

Member	Description
request_id	A number uniquely identifying the request
variables	An object with PHP superglobal variables (_SERVER, _GET etc)

variables

The variables member contains PHP superglobal variables with the following members:

Member	Description
values	An object with all the PHP superglobal variable values
old_values	An object with all the old values in case they changed

Example

{"event":"zray.SUPERGLOBALS","params":
    {"request_id":8,"variables":{
        "_GET":{"sid":"834783749"},
        "_SERVER":{"HTTP_ACCEPT_ENCODING":"gzip, deflate"}
    }}
}

zray.REQUEST_HEADERS event

The zray.REQUEST_HEADERS notification event is sent out at the end of the request and contains all the request headers sent to the PHP. The params member contains the following members:

Member	Description
request_id	A number uniquely identifying the request
headers	An array with request header strings

Example

{"event":"zray.REQUEST_HEADERS","params":
    {"headers":["Host: localhost:8080","Accept-Language: en-gb",
     "Accept-Encoding: gzip, deflate","Connection: keep-alive"],
     "request_id":4}}

zray.RAW_POST_DATA event

The zray.RAW_POST_DATA notification event is sent out at the end of the request and contains the raw post data if the request method was POST. The params member contains the following members:

Member	Description
request_id	A number uniquely identifying the request
data	A string containing the raw post data

Example

{"event":"zray.RAW_POST_DATA","params":{"data":"name=John","request_id":5}}

zray.RESPONSE_HEADERS event

The zray.RESPONSE_HEADERS notification event is sent out at the end of the request and contains all the response headers sent out by the PHP. The params member contains the following members:

Member	Description
request_id	A number uniquely identifying the request
headers	An array with response headers

Example

{"event":"zray.RESPONSE_HEADERS","params":
    {"headers":["Set-Cookie: zraytok=BMy5YAAAAAC3oXNviy5-EAAAANA; Max-Age:86400",
        "Content-type: text/html; charset=UTF-8"],
     "request_id":4}}

zray.RESPONSE_BODY event

The zray.RESPONSE_BODY notification event is sent out at the end of the request and contains the raw response body sent out by the PHP. The params member contains the following members:

Member	Description
request_id	A number uniquely identifying the request
content_type	The type of the content as a string
body	The base64 encoded raw response body as a string

Example

{"event":"zray.RESPONSE_BODY","params":
    {"content_type": "text/html; charset=UTF-8",
     "body":"PGh0bWw+XG48aGVhZD5cbjwvaGVhZD5cbjxib2R5PlxuXG48cD5IZWxsbyA8Yj5Kb2huPC9iPiBm
cm9tIE15Q2xhc3M8L3A+XG48cD5HcmVldCBzb21lYm9keSBlbHNlPC9wPlxuPGZvcm0gYWN0aW9u
PVwidGVzdC5waHBcIiBtZXRob2Q9XCJwb3N0XCI+XG4gICAgTmFtZTogPGlucHV0IHR5cGU9XCJ0
ZXh0XCIgbmFtZT1cIm5hbWVcIj48YnI+XG4gICAgPGlucHV0IHR5cGU9XCJzdWJtaXRcIj5cbjwv
Zm9ybT5cblxuPC9ib2R5PlxuCg==",
     "request_id":5}}

Namespace "zrayh"

The zrayh namespace manages Z-Ray historical data. Clients can query Z-Ray historical data. The client must have a session associated with it and the ZendHQ license must be valid.

zrayh.version method

Requests the zrayh namespace API version number from the server.

Request

Member	Description
method	Fixed string "zrayh.version"

Response

The result member contains the following values.

Member	Description
major	The Z-Ray API major version number
minor	The Z-Ray API minor version number

Example

C->S {"id":1,"method":"zrayh.version"}
S->C {"id":1,"result":{"major":1,"minor":2}}

zrayh.get_requests method

Requests a list of historical Z-Ray requests. Use optional params members to get a filtered response. The default is to return up to 50 last requests stored in the database.

Request

Member	Description
method	Fixed string "zrayh.get_requests"
params	A JSON object with method parameters

The params member can contain the following values:

Member	Description
count	Maximum number of requests included in the response
filter	A JSON object with request filters

The filter object can contain the following members:

Member	Description
time_sec_from	A JSON value with the UNIX time
time_sec_to	A JSON value with the UNIX time
method	A JSON value or an array with request methods
response_code	A JSON value or an array with response codes

The time_sec_from member contains a JSON value with the UNIX time. Only requests with a request time equal or greater than this value are included in the response.

Without the time_sec_from member there is no lower limit for request times.

The time_sec_to member contains a JSON value with the UNIX time. Only requests with a request time less than this value are included in the response.

Without the time_sec_to member there is no upper limit for response times.

The method member contains a single JSON value or an array or values with request methods to include in the response. You can use the following values:

• GET

• POST

• CLI

Without the method member requests with any request method are included in the response.

The response_code member contains a single JSON value or an array of values with request response codes to include in the response. You can use the following values:

• 2xx - matches any successful responses (200-299)

• 3xx - matches any redirect responses (300-399)

• 4xx - matches any client error responses (400-499)

Without the response_code member requests with any response code are included in the response.

Response

The result member contains an array of historical Z-Ray requests as JSON objects with the following members:

Member	Description
request_id	A number uniquely identifying the request
time_sec	UNIX time of the request
time_usec	Microseconds of the request time
method	The request method ("GET" or "POST")
target	The target of the request
http_response_code	The HTTP response code sent to the browser
total_time	Time it took to process the request in milliseconds
error_severity	An integer value indicating notices, warnings, and errors

The error_severity member indicates the most severe notice, warning or error message associated with the request and can have one of the following values:

• 0 - No PHP notice, warning or error messages; may have PHP exceptions

• 1 - Has at least one PHP notice

• 2 - Has at least one PHP warning

• 3 - Has at least one PHP error

Example

C->S {"id":1,"method":"zrayh.get_requests","params":{"filter":{"time_sec_from":1622631000,"method":"GET"}}}
S->C {"id":1,"result":[{"error_severity":0,"http_response_code":200,"method":"GET","request_id":3,
         "target":"http://localhost:8080/test.php?zraytok=zbS4YAAAAADWhdgnCbk6eAAAAP8",
         "time_sec":1622631380,"time_usec":708572,"total_time":2.8090476989746094}]}

zrayh.get_request method

Requests all the data for a single Z-Ray historical request.

Request

Member	Description
method	Fixed string "zrayh.get_requests"
params	A JSON object with method parameters

The params member must contain the following values:

Member	Description
request_id	The ID of the request

Response

The result member contains a JSON object with the request details and contains the following members:

Member	Description
request_id	The ID of the request
rinit	zray.RINIT event members
rshutdown	zray.RSHUTDOWN event members
errors	An array of errors with zray.ERROR event members
functions	An array of function statistics
user_data	An array of user data objects with zray.STORAGE event members
superglobals	An array of PHP superglobal variables
request_headers	An array of request headers
raw_post_data	A string containing the raw post data
response_headers	An array of response headers
response_body	zray.RESPONSE_BODY event members

zrayh.delete_request method

Deletes the request(s) and all the related data.

Request

Member	Description
method	Fixed string "zrayh.delete_request"
params	A JSON object with method parameters

The params member must contain the following values:

Member	Description
request_id	The ID of the request (can be an array of ID values)

Response

The result member contains the fixed string "OK". Note that the method succeeds even if there were no such requests.

Namespace "mon"

The mon namespace manages Monitoring data. Clients can query collected monitoring issues and events.

Monitoring event is a single occurrence of an event. Every monitoring event is associated with one and only one monitoring issue. If you have enabled monitoring event aggregation in the configuration, then you can associate multiple monitoring events with the same monitoring issue.

The client must have a session associated with it and the ZendHQ license must be valid.

mon.version method

Requests the mon namespace API version number from the server.

Request

Member	Description
method	Fixed string "mon.version"

Response

The result member contains the following values.

Member	Description
major	The Monitoring API major version number
minor	The Monitoring API minor version number

Example

Client:

{"id":1,"method":"mon.version"}

Server:

{"id":1,"result":{"major":1,"minor":2}}

mon.subscribe method

Subscribes the client to the Monitoring real-time data notifications mon.issue.

Request

Member	Description
method	Fixed string "mon.subscribe"

Response

The result member contains the fixed string "OK".

Example

Client:

{"id":1,"method":"mon.subscribe"}

Server:

{"id":1,"result":"OK"}

mon.unsubscribe method

Unsubscribes the client from the Monitoring real-time data notifications.

Request

Member	Description
method	Fixed string "mon.unsubscribe"

Response

The result member contains the fixed string "OK".

Example

Client:

{"id":1,"method":"mon.unsubscribe"}

Server:

{"id":1,"result":"OK"}

mon.load_default_rules method

Loads default monitoring rules from the default_monitor_rules.json file and replaces current monitoring rules with the default rules.

Request

Member	Description
method	Fixed string "mon.load_default_rules"

Response

The result member contains the fixed string "OK".

Example

Client:

{"id":1,"method":"mon.load_default_rules"}

Server:

{"id":1,"result":"OK"}

mon.issue event

The mon.issue notification event is sent out for every time a new monitoring issue is created or an existing issue is updated.

Data structure for the notification is the same as described in mon.get_issues except that a single data object is included in the event.

mon.get_issues method

Requests a list of issues. Use optional params members to get a filtered response. The default is to return up to 50 last issues stored in the database.

Request

Member	Description
method	Fixed string "mon.get_issues
params	A JSON object with method parameters

The params member can contain the following values:

Member	Description
count	Maximum number of issues included in the response
request_id	Optional request ID value

The optional request_id parameter can be used to filter monitoring issues that contain monitoring events with the given request ID value.

Response

The result member contains an array of historical monitoring issues as JSON objects with the following members:

Member	Description
issue_id	A number uniquely identifying the issue
time_sec	UNIX time of the last event
name	Rule name what caused the event generation
severity	Event severity level
count	Aggregated events count
code_trace_id	Optional request ID of the last Code Trace
task_id	Optional ID of the last Job Queue task

The severity member indicates severity of the issue and can have one of the following values:

• "notice"

• "warning"

• "critical"

Example

Client:

{"id":1,"method":"mon.get_issues","params":{"count":10}}

Server:

{"id":1,"result":[{"event_id":1,"time_sec":1622631380, "name":"Slow request", "severity":"critical", "count": 1}]}

mon.get_issue method

Requests the issue details.

Request

Member	Description
method	Fixed string "mon.get_issue"
params	A JSON object with method parameters

The params member must contain the following value:

Member	Description
issue_id	The ID of the issue

Response

The result member contains a JSON object with the following members:

Member	Description
issue_id	A number uniquely identifying the issue
request_id	A number uniquely identifying the request
name	Event name, based on rule name
type	Type of the event
severity	Event severity level
time_sec	UNIX time of the event
time_first_sec	UNIX time of the first event (when aggregated)
count	The count of something, unclear
has_code_trace	yes / no / pending
code_trace_id	Optional request ID of the last Code Trace
request	Optional request data object
function	Optional function data object
error	Optional error data object
stack_trace	Optional stack trace
custom	Optional custom event data object
variables	Optional $_SERVER, $_REQUEST, etc
actions	Optional, actions taken
exec_time_msec	Optional function/query execution time in msec
memory_usage_bytes	Optional memory usage in bytes
task_id	Optional ID of the last Job Queue task
exec_failure	Optional Job Queue task execution failure
exec_delay_sec	Optional Job Queue task execution delay
job	Optional Job Queue job data object

request

Member	Description
url	Request URL
php_version	The PHP version string
node_name	Name of the node that processed the request
pid	Process ID of the PHP process that processed the request

function

Member	Description
function_name	Function name
file_name	Full path for php file where event occurred
line_no	Line number in the file
function_args	An array with function arguments

error

Member	Description
message	The exception message
error_type	Type of the error
error_type_str	Short description of the error type
file_name	The filename where the exception was created
line_no	The line where the exception was created

variables

The variables member contains an object with PHP superglobal variables with the following members:

Member	Description
value	An object with all the PHP superglobal variable values

stack_trace

The stack_trace member contains an array of frame objects with the following members:

Member	Description
function_name	Name of the function
file_name	Full name of the PHP source file
line_no	The line number if the PHP source file

custom

The custom member contains an object with Custom Event data and can have the following members:

Member	Description
type	Optional type string
text	Optional text
user_data	Optional user data

actions

The actions member contains an array of action objects with the following members:

Member	Description
email	Email address where notification was sent to, or empty
callback_url	URL what was called, or empty
status	Optional status of the action

job

The job member contains an object with Job Queue job data and CAN have the following members:

Member	Description
job_id	ID of the job
job_name	Optional name of the job
queue_id	ID of the queue
queue_name	Name of the queue
reason	Optional reason of the job execution failure
script	The CLI job script with all the arguments
url	The HTTP job url
type	Type of the job (one of cli or http)

Example

Client:

{"id":1,"method":"mon.get_issue","params":{"issue_id":33}}

Server:

{
  "issue_id": 33, "request_id": 1, "name": "Rule no 1", "severity": "critical", "time_sec": 1646831923, 
  "time_first_sec": 1641831923, "count": 1, "has_trace": "pending",
  "request": {"url": "http://10.1.1.10/sample/mtrig.php", "pid": 1, "node_name": "zebra01", "php_version": "7.3.11"},
  "source": {"file_name": "/usr/local/zend/var/apps/http/__default__/0/sample/2.0_2/public/mtrig.php",
           "function_name": "functionName","line_no": 17, "function_args":[]},
  "error": {"message": "Exception", "code": 3, "file_name": "index.php", "line_no": 10},
  "stack_trace": [{"file_name":"index.php","function_name":"{main}","line_no":1}],
  "variables": {"_SERVER":{"values":{}},"_REQUEST":{"values":{}}},
  "actions": {"email": "", "callback_url": ""}
}

mon.get_events method

Requests a list of events associated with an issue. By default, the number of events in the response is limited to 50 events.

Request

Member	Description
method	Fixed string "mon.get_events
params	A JSON object with method parameters

The params member must contain at least one the following values:

Member	Description
issue_id	The ID of the issue
request_id	The ID of the request

The params member can contain the following additional values:

Member	Description
count	Maximum number of events included in the response

Response

The result member contains an array of historical monitoring events as JSON objects with the following members:

Member	Description
event_id	A number uniquely identifying the event
issue_id	A number uniquely identifying the issue
request_id	A number uniquely identifying the request
has_code_trace	yes / no / pending
time_sec	UNIX time of the last event
name	Rule name what caused the event generation
severity	Event severity level

The severity member indicates severity of the issue and can have one of the following values:

• "notice"

• "warning"

• "critical"

Example

Client:

{"id":1,"method":"mon.get_events","params":{"issue_id":10}}

Server:

{"id":1,"result":[{"event_id":1, "issue_id":10, "time_sec":1622631380, "name":"Slow request", "severity":"critical"}]}

mon.get_event method

Requests the event details.

Request

Member	Description
method	Fixed string "mon.get_event"
params	A JSON object with method parameters

The params member must contain the following value:

Member	Description
event_id	The ID of the event

Response

The result member contains a JSON object and canhave the following members:

Member	Description
event_id	A number uniquely identifying the event
issue_id	A number uniquely identifying the issue
request_id	A number uniquely identifying the request
name	Event name, based on rule name
type	Type of the event
severity	Event severity level
time_sec	UNIX time of the event
has_code_trace	yes / no / pending
request	Optional request data object
function	Optional function data object
error	Optional error data object
stack_trace	Optional stack trace
custom	Optional custom event data object
variables	Optional _SERVER, _REQUEST, etc
actions	Optional, actions taken
exec_time_msec	Optional function/query execution time in msec
memory_usage_bytes	Optional memory usage in bytes
task_id	Optional ID of the last Job Queue task
exec_failure	Optional Job Queue task execution failure
exec_delay_sec	Optional Job Queue task execution delay
job	Optional Job Queue job data object

See mon.get_issue for the member value details.

Example

Client:

{"id":3,"method":"mon.get_event","params":{"event_id":1}}

Server:

{
  "id":3,
  "result":{"event_id":1, "issue_id": 33, "request_id": 1, "name": "Rule no 1", 
            "severity": "critical", "time_sec": 1646831923, "has_trace": "pending",
            "request": {"url": "http://10.1.1.10/sample/mtrig.php", "pid": 1,
                        "node_name": "zebra01", "php_version": "7.3.11"},
           "source": {"file_name": "/usr/local/zend/var/apps/http/__default__/0/sample/2.0_2/public/mtrig.php",
                      "function_name": "functionName","line_no": 17, "function_args":[]},
           "error": {"message": "Exception", "code": 3, "file_name": "index.php", "line_no": 10},
           "stack_trace": [{"file_name":"index.php","function_name":"{main}","line_no":1}],
           "variables": {"_SERVER":{"values":{}},"_REQUEST":{"values":{}}},
           "actions": {"email": "", "callback_url": ""}
  }
}

mon.delete_issue method

Deletes an issue and all the related data.

Request

Member	Description
method	Fixed string "mon.delete_issue"
params	A JSON object with method parameters

The params member must contain the following value:

Member	Description
issue_id	The ID of the issue

Response

The result member contains the fixed string "OK".

Example

Client:

{"id":1,"method":"mon.delete_issue","params":{"issue_id":1}}

Server:

{"id":1,"result":"OK"}

mon.delete_event method

Deletes an event and all the related data. If this is the only event associated with an issue, then the issue is deleted too. Otherwise, the issue is update to reflect the deleted event.

Request

Member	Description
method	Fixed string "mon.delete_event"
params	A JSON object with method parameters

The params member must contain the following value:

Member	Description
event_id	The ID of the event. Can be an array of ID values.

Response

The result member contains the fixed string "OK". Note that the method succeeds even if there were no such events.

Example

Client:

{"id":1,"method":"mon.delete_event","params":{"event_id":[1,2]}}

Server:

{"id":1,"result":"OK"}

Namespace "ct"

The ct namespace manages Code Tracing data. Clients can query collected Code Tracing dumps.

A Code Tracing dump is a collection of PHP cod execution checkpoints with associated data. Code Tracing dumps are stored as binary blobs and processed in the background. Code Tracing dumps become available only after they are processed.

The client must have a session associated with it and the ZendHQ license must be valid.

ct.version method

Requests the ct namespace API version number from the server.

Request

Member	Description
method	Fixed string "ct.version"

Response

The result member contains the following values:

Member	Description
major	The Code Tracing API major version number
minor	The Code Tracing API minor version number

Example

Client:

{"id":1,"method":"ct.version"}

Server:

{"id":1,"result":{"major":1,"minor":0}}

ct.subscribe method

Subscribes the client to the Code Tracing data notification ct.trace_stored and ct.trace_status events.

Request

Member	Description
method	Fixed string "ct.subscribe"

Response

The result member contains the fixed string "OK".

Example

Client:

{"id":1,"method":"ct.subscribe"}

Server:

{"id":1,"result":"OK"}

ct.unsubscribe method

Unsubscribes the client to the Code Tracing data notifications.

Request

Member	Description
method	Fixed string "ct.unsubscribe"

Response

The result member contains the fixed string "OK".

Example

Client:

{"id":1,"method":"ct.unsubscribe"}

Server:

{"id":1,"result":"OK"}

ct.load_default_functions method

Loads the list of traced PHP internal functions from the default_traced_functions.json file and replaces the current list of traced PHP internal functions with the default one.

Request

Member	Description
method	Fixed string "ct.load_default_functions"

Response

The result member contains the fixed string "OK".

Example

Client:

{"id":1,"method":"ct.load_default_functions"}

Server:

{"id":1,"result":"OK"}

ct.get_traces method

Requests a list of Code Tracing traces. Use optional params members to get a filtered response. The default is to return up to 50 last traces stored in the database.

Request

Member	Description
method	Fixed string "ct.get_traces"
params	A JSON object with method parameters

The params member CAN contain the following values:

Member	Description
count	Maximum number of traces included in the response

Response

The result member contains an array of Code Tracing traces as JSON objects with the following members:

Member	Description
request_id	The request ID
dump_reason	Reason for the Code Tracing trace
status	Status of the Code Tracing trace
time_sec	UNIX time of the trace
url	the URL of the request
node_name	The name of the node that generated the trace
trace_size	Total size (bytes) of the trace dump and json files

The dump_reason member indicates the reason for the Code Tracing trace and CAN have one of the following values:

Member	Description
event	Triggered by a Monitoring event
request	Triggered by request parameters
user	Triggered by the PHP user script

Example

Client:

{"id":1,"method":"ct.get_traces","params":{"count":10}}

Server:

{"id":1,
 "result":[
	{
	   "dump_reason": "request",
	   "node_name": "node1",
	   "request_id": 2091,
	   "status": "processed",
	   "time_sec": 1661498681,
          "trace_size": 2730,
	   "url": "http://localhost:8080/test.php?dump_data=1"
	}
  ]
}

ct.get_trace method

Requests the Code Tracing trace identified by a request ID value. The Code Tracing trace must be processed before the trace can be requested.

Request

Member	Description
method	Fixed string "ct.get_trace"
params	A JSON object with method parameters

The params member must contain the following value:

Member	Description
request_id	The request ID value

Response

The result member contains an array of Code Tracing trace as a JSON object with the following members:

Member	Description
request_id	The request ID
dump_reason	Reason for the Code Tracing trace
time_sec	UNIX time of the trace
trace_size	Total size (bytes) of the trace dump and json files
url	the URL of the request
node_name	The name of the node that generated the trace
cp	An array of Code Tracing checkpoints
fn	An array of PHP function entries
cl	An array of PHP class entries

See the Code Trace JSON file documentation for cp, fn, and cl array details.

ct.delete_trace method

Deletes the Code Tracing trace(s) and all the related data using the request ID value as identifier.

Request

Member	Description
method	Fixed string "ct.delete_trace"
params	A JSON object with method parameters

The params member must contain the following value:

Member	Description
request_id	The ID of the request (can be an array of ID values)

Response

The result member contains the fixed string "OK". Note that the method succeeds even if there were no traces with such request ID values.

ct.trace_stored event

The ct.trace_stored notification event is sent out when a new Code Tracing trace is received and stored on the server. The `params` member contains the following values:

Member	Description
request_id	The request ID
dump_reason	Reason for the Code Tracing trace
status	Fixed string "stored"
time_sec	UNIX time of the trace
trace_size	Size (bytes) of the trace dump file
url	the URL of the request
node_name	The name of the node that generated the trace

Example

Server:

{
	"event": "ct.trace_stored",
	"params": {
		"dump_reason": "request",
		"node_name": "node1",
		"request_id": 2092,
		"status": "stored",
		"time_sec": 1661500680,
		"trace_size": 910,
		"url": "http://localhost:8080/test.php?dump_data=1"
	}
}

ct.trace_status event

The ct.trace_status notification event is sent out when a Code Tracing trace status changes on the server. The params member contains the following values:

Member	Description
request_id	The request ID
status	New Code Tracing trace status
trace_size	Optional total size (bytes) of the trace dump and json file

The status member can have one of the following values:

Member	Description
processed	The Code Tracing trace is processed on the server
deleted	The Code Tracing trace is deleted on the server

Example

Server:

{
   "event": "ct.trace_status",
   "params": {
       "request_id": 2092,
	"status": "processed",
	"trace_size": 2730
    }
}

 

Namespace "jq"

The jq namespace manages Job Queue jobs and queues.

• A Job Queue job is a task that ZendHQ executes asynchronously on the ZendHQ daemon’s node or optionally on PHP nodes. The job can, for example, perform an HTTP request to a specific server.

• A Job Queue queue is a scheduler that executes tasks one by one. The execution order is determined by the schedule and priority of jobs. Clients can create multiple Job Queue queues to execute tasks in parallel.

The client must have a session associated with it and the ZendHQ license must be valid.

Queue identifier

Job Queue queues are identified by a name or a numeric ID value. The jq namespace handler allows entering queue identifiers in multiple ways:

• as a JSON object with elements name or id;

• as a JSON string value with the name of the queue;

• as a JSON numeric value with the ID value of the queue.

Queue name must be more than zero and less 256 characters long.

Queue ID value must be a positive integer value including zero.

The special ID value 0 is used to identify the default queue even if the default queue has a different ID value.

The following are valid queue identifiers:

"queue":{"name":"feeds"}

"queue":{"id":2}

"queue":"feeds"

"queue":2

Default Queue

The Job Queue always has a default queue, which cannot be deleted. By default, the default queue is identified by the queue name "__default__". The ID value 0 always identifies the default queue even if the actual ID value is different.

jq.version method

Requests the jq namespace API version number from the server.

Request

Member	Description
method	Fixed string "jq.version"

Response

The result member contains the following values:

Member	Description
major	The Job Queue API major version number
minor	The Job Queue API minor version number

Example

Client:

{"id":1,"method":"jq.version"}

Server:

{"id":1,"result":{"major":1,"minor":0}}

jq.subscribe method

Subscribes the client to Job Queue notification events. Replaces any previous Job Queue subscriptions for the same client.

Request

Member	Description
method	Fixed string "jq.subscribe"
params	Optional JSON object with subscription filters

The params member CAN contain the following elements:

Member	Description
queue	Queue identifier or JSON array with queue identifiers
job_id	Job ID value or JSON array with job ID values (see notes below)
task_id	Task ID value or JSON array with task ID values (see notes below)

Without any elements in the subscription filter, the client is subscribed to all the Job Queue notifications events.

With a queue element as an empty JSON array, the client is subscribed to all the queue related events.

With a queue elements as a single queue identifier or a JSON array with queue identifiers, the client is subscribed to specific queue related events.

Elements job_id and task_id are currently trigger elements and can have any value. At least one valid queue identifier must be specified in the queue element for these elements to be accepted.

If the job_id element exists with any values, then the client is also subscribed to all the job related events within specified queues.

If the task_id element exists with any values, then the client is also subscribed to all the task related events within specified queues.

Notice that the preferred value for job_id and task_id elements is an empty JSON array, which is future proof and keeps working the same way when additional job or task filtering is added.

Response

The result member contains the fixed string "OK".

Example

Client subscribes to all the queue and job related notification events in the queue “feeds”:

Client:

{"id":2,"method":"jq.subscribe","params":{"queue":{"name":"feeds"},"job_id":[]}}

Server:

{"id": 2, "result": "OK"}

jq.unsubscribe method

Unsubscribes the client from Job Queue notification events.

Request

Member	Description
method	Fixed string "jq.unsubscribe"

Response

The result member contains the fixed string "OK".

Example

Client unsubscribes from all the Job Queue notification events:

Client:

{"id":3,"method":"jq.unsubscribe"}

Server:

{"id": 3, "result": "OK"}

jq.add_queue method

Adds a queue to the Job Queue.

Triggers the "jq.queue_status" notification event.

Request

Member	Description
method	Fixed string "jq.add_queue"
params	JSON object with method parameters

The params member must contain the following values:

Value	Description
name	Name uniquely identifying the queue

The name member value is a string up to 256 characters uniquely identifying the queue. The name member value cannot be empty.

The params member can contain the following additional values:

Value	Description
suspended	JSON boolean true value for creating suspended queues
priority	Priority of the queue
job_defaults	JSON object with default values for jobs added to this queue

If the optional suspended member value is a JSON boolean value true, then the queue is created in the suspended state. By default, queues are active when created.

The optional priority member specifies the priority of the queue and must have one of the following values:

Queue priority values

Value	Description
low	queue is running at low priority
normal	queue is running at normal priority (default)
high	queue is running at high priority
urgent	queue is running at urgent priority

Queue priority value affects operating system scheduling policies and if two Job Queue queue schedulers are waking up at the same time, then the higher priority queue is scheduled first.

Queue priority value also affects the accuracy of scheduling timers. Higher priority queues are more likely executing jobs at the exact time scheduled for the job.

Notice that higher priority queues are more cpu intensive and can actually cause queue starvation if abused.

The job_defaults member specifies default values for jobs added to this queue and CAN have the following values:

Job Defaults

Member	Description
type	Default job type
priority	Default job priority
timeout	Default timeout value in seconds
max_retry_count	Maximum number of retries
retry_delay	Delay in seconds between retries
http_method	Default HTTP request method for HTTP jobs
http_content_type	Default content type for HTTP jobs
validate_ssl	Default validate SSL certificates option for HTTP jobs
persist	Default persist job option value
persist_output	Default persist job output option value

The optional type member specifies the default job type for jobs added to this queue.

The optional priority member specifies the default job priority for jobs added to this queue.

The optional timeout member specifies the default timeout time in seconds for jobs in this queue. The value must

be a positive integer value greater than zero and less than 2147484.

The optional max_retry_count member specifies the default maximum number of retries for jobs in this queue. The value must be a positive integer value including zero.

The optional retry_delay member specifies the default delay time in seconds between retries. The value must be a positive integer value including zero and less than 2147484.

The optional http_method member specifies the default HTTP request method for HTTP jobs in this queue.

The optional http_content_type member specifies the default HTTP content type for HTTP POST and PUT jobs in this queue.

The optional validate_ssl member specifies the default validate SSL option for HTTP jobs over SSL in this queue.

The optional persist member specifies the default persist job option for jobs in this queue.

The optional persist_output member specifies the default persist job output option for jobs in this queue.

Application default values are used for missing elements.

Response

The result member contains the ID value uniquely identifying the added queue.

Example

Add a Job Queue queue with the name "feeds" and the default job timeout value 60 seconds:

Client:

{"id":3,"method":"jq.add_queue","params":{"name":"feeds","job_defaults":{"timeout":60}}}

Server:

{"id": 3, "result": 2}

jq.update_queue method

Modifies an existing queue in the Job Queue. Changing job default values does not affect existing jobs in the queue.

Triggers the "jq.queue_status" notification event.

Request

Member	Description
method	Fixed string "jq.update_queue"
params	JSON object with method parameters

The params member must contain the following values:

Value	Description
queue	Queue identifier uniquely identifying the queue

The params member CAN contain the following values:

Value	Description
name	New name of the queue
priority	New priority of the queue
job_defaults	JSON object with new default values for jobs added to this queue

See the jq.add_queue method for member details.

Response

The result member contains the ID value of the updated queue.

Example

Change the name of the queue from "feeds" to "news":

Client:

{"id":4,"method":"jq.update_queue","params":{"queue":{"name":"feeds"},"name":"news"}}

Server:

{"id":4,"result":2}

jq.delete_queue method

Deletes a queue from the Job Queue. The queue must be suspended before it can be deleted. All the jobs in the queue are deleted too.

Notice that the default queue cannot be deleted.

Triggers the "jq.queue_status" notification event.

Request

Member	Description
method	Fixed string "jq.delete_queue"
params	JSON object with method parameters

The params member must contain the following values:

Value	Description
queue	Queue identifier uniquely identifying the queue

Response

The result member contains the fixed string "OK".

Example

Delete the queue with the name "feeds":

Client:

{"id":4,"method":"jq.delete_queue","params":{"queue":{"name":"feeds"}}}

Server:

{"id":4,"result":"OK"}

jq.has_queue method

Checks that a queue exists in the Job Queue.

Request

Member	Description
method	Fixed string "jq.has_queue"
params	JSON object with method parameters

The params member must contain the following values:

Value	Description
queue	Queue identifier uniquely identifying the queue

Response

The result member contains a JSON boolean true or false value.

Example

Check that a queue with the name "news" exists:

Client:

{"id":5,"method":"jq.has_queue","params":{"queue":{"name":"news"}}}

Server:

{"id":5,"result":false}

jq.suspend_queue method

Suspends a Job Queue queue. Suspended queues accept new jobs, but do not execute them while the queue is suspended.

If a job is currently running in the queue, then the queue is not suspended until the job is finished. The method still returns with an ok status.

Triggers the "jq.queue_status" notification event when the queue is suspended.

Request

Member	Description
method	Fixed string "jq.suspend_queue"
params	JSON object with method parameters

The params member CAN contain the following values:

Value	Description
queue	Queue identifier uniquely identifying the queue

Suspends the default queue if the queue identifier is not given.

Response

The result member contains the fixed string "OK".

Example

Suspend the queue with the name "feeds":

Client:

{"id":5,"method":"jq.suspend_queue","params":{"queue":{"name":"feeds"}}}

Server:

{"id":5,"result":"OK"}

jq.activate_queue method

Activates a Job Queue queue. If the queue was previously suspended, then reschedules all the jobs based on their scheduled execution time and priority.

Triggers the "jq.queue_status" notification event if the queue is activated.

Request

Member	Description
method	Fixed string "jq.activate_queue"
params	JSON object with method parameters

The params member CAN contain the following values:

Value	Description
queue	Queue identifier uniquely identifying the queue

Activates the default queue if the queue identifier is not given.

Response

The result member contains the fixed string "OK".

Example

Activate the default queue:

Client:

{"id":5,"method":"jq.activate_queue"}

Server:

{"id":5,"result":"OK"}

jq.is_queue_suspended method

Checks that a queue is suspended.

Request

Member	Description
method	Fixed string "jq.is_queue_suspended"
params	JSON object with method parameters

The params member can contain the following values:

Value	Description
queue	Queue identifier uniquely identifying the queue

Checks the default queue if the queue identifier is not given.

Response

The result member contains a JSON boolean true or false value.

Example

Check that the queue with the name "feeds" is suspended:

Client:

{"id":5,"method":"jq.is_queue_suspended","params":{"queue":{"name":"feeds"}}}

Server:

{"id":5,"result":false}

jq.get_queues method

Returns a list of all the queues in the Job Queue.

Request

Member	Description
method	Fixed string "jq.get_queues"

Response

The result member contains a JSON array with zero or more queue objects.

Job Queue object The Job Queue queue object contains the following values:

Value	Description
id	A numeric value uniquely identifying the queue
name	A name uniquely identifying the queue
jobs_count	Number of scheduled jobs in the queue
priority	Queue priority value
status	Queue status value
default	Optional JSON boolean true value identifying the default queue

Queue Status values

Value	Description
running	Active (running) queue
suspended	Suspended queue
deleted	Deleted queue

Example

Client:

{"id":5,"method":"jq.get_queues"}

Server:

{
  id": 5,
  "result": [
    {"default": true, "id": 1, "jobs_count": 0, 
     "name": "__default__", "priority": "normal", "status": "running"},
    {"id": 2,"jobs_count": 2,"name": "feeds","priority": "normal","status": "running"}
  ]
}

jq.get_queue method

Returns queue details.

Request

Member	Description
method	Fixed string "jq.get_queue"
params	JSON object with method parameters

The params member CAN contain the following values:

Value	Description
queue	Queue identifier uniquely identifying the queue

Returns the default queue details if the queue identifier is not given.

Response

The result member contains a JSON object with the following values:

Value	Description
id	A numeric value uniquely identifying the queue
name	A name uniquely identifying the queue
jobs_count	Number of scheduled jobs in the queue
priority	Queue priority value
status	Queue status value
default	Optional JSON boolean true value identifying the default queue
job_defaults	Job default values

Example

Get details of the queue identified by the name "feeds":

Client:

{"id":5,"method":"jq.get_queue","params":{"queue":{"name":"feeds"}}}

Server:

{
  "id": 5,
  "result": {
    "id": 2,
    "job_defaults": 
      {"max_retries": 2, "persist": false, "persist_output": "no", "priority": "normal",
      "retry_delay": 1, "timeout": 60 },
    "jobs_count": 5,"name": "feeds","priority": "normal","status": "running"}
}

jq.add_job method

Adds a new job to the Job Queue.

Triggers "jq.queue_status" and "jq.job_status" notification events.

Request

Member	Description
method	Fixed string "jq.add_job"
params	JSON object with method parameters

The params object CAN contain the following values:

Value	Description
type	Type of the job
name	Name of the job
queue	Queue identifier uniquely identifying the queue
predecessor	Predecessor job ID value
priority	Priority of the job
timeout	Job timeout value in seconds
max_retry_count	Maximum number of retries
retry_delay	Delay in seconds between retries
schedule	JSON object with the schedule
persist	Persist job option
persist_output	Persist job output option
url	The request URL for HTTP jobs
http_method	HTTP request method for HTTP jobs
http_headers	HTTP request headers for HTTP jobs
http_query_args	HTTP request query arguments for HTTP jobs
validate_ssl	Validate SSL certificates option for HTTP jobs
http_content_type	HTTP body content type for HTTP POST and PUT jobs
http_body_vars	HTTP body variables for HTTP POST and PUT jobs
http_raw_body	Raw HTTP body for HTTP POST and PUT jobs
script	Name of the script for CLI jobs
env	Environment variables for CLI jobs
nodes	Regular expression specifying node names for CLI jobs

The optional type member specifies the type of the job and CAN have one of the following values:

Job type values

Value	Description
http	HTTP request
cli	Command-line script

The optional name member gives the job a name, which must be unique within the queue.

The optional queue member specifies the queue. If the queue member is omitted, then the job is added to the default queue.

The optional predecessor member specifies the predecessor job. The new job is executed only after the predecessor job is completed sucessfully. The predecessor job must be scheduled and not running before adding this job.

The optional priority member specifies the priority of the job and must have one of the following values:

Job priority values

Value	Description
low	Low priority
normal	Normal priority
high	High priority
urgent	Urgent priority

The priority value is used to determine the execution order of jobs if all the other attributes are equal, i.e. when two jobs are about to be executed at the same time, then the job with the higher priority is executed first.

The optional timeout member specifies the job execution timeout time in seconds and must be a positive integer value greater than zero and less than 2147484.

The optional max_retry_count member specifies the maximum number of retries if the job fails to execute due to an error or timeout. The value must be a positive integer value including zero.

The optional retry_delay member specifies the wait time in seconds between retries and must be a positive integer value including zero and less than 2147484.

The optional schedule member specifies when the job is executed and must contain one of the following members:

Job schedule

Member	Description
unix_time	Execution time as number of seconds since the EPOCH (1970-01-01T00:00:00Z)
date_time	Execution time as date/time string
cron	Recurring job with a cron-like schedule

The date_time member must be using either the ISO 8601 extended format yyyy-mm-ddThh:mm:ss[<TZ>] or the relative time format +[[hh:]mm:]ss. The optional <TZ> time-zone suffix must be either Z for UTC or an offset as [+|-]hh:mm.

It is strongly suggested to always specify the time zone. Otherwise the time zone of the machine where the ZendHQ daemon process runs is used.

The following are valid date_time member values:

• "2023-04-30T13:20:00Z"

• "2023-04-30T16:20:00+03:00"

• "+05:00"

The cron member specifies a recurring schedule using the following format:

<seconds> <minutes> <hours> <day-of-month> <month> <day-of-week>

Field	Allowed values	Allowed special characters
seconds	0-59	* , - /
minutes	0-59	* , - /
hours	0-23	* , - /
day-of-month	1-31	* , - /
month	1-12 or JAN-DEC	* , - /
day-of-week	0-7 SUN-SAT (MON-SUN)	* , - /

If the schedule member is omitted, then the job is scheduled to be executed immediately.

The optional persist member can be used to make jobs and their execution history persistent and must have a JSON boolean true or false value.

Job persist values

• true - the job and its execution history is never deleted during the database cleanup. Use this option with care.

• false - the job and its execution history can be deleted during the regular database cleanup.

The optional persist_output member specifies what to do with job execution output and must have one of the following values:

Job persist output values

Value	Description
yes	Job execution output is always stored
no	Job execution output is never stored
error	Job execution output is stored on errors

If the type member value is http, then the params object must contain the following values:

Value	Description
url	The request URL

The url member specifies the request URL for HTTP jobs and must be a valid URL with a http:// or https:// prefix.

If the type member value is http, then the params object can contain the following additional values:

Value	Description
http_method	The HTTP request method
http_headers	HTTP request headers
http_query_args	HTTP request query arguments
validate_ssl	Validate SSL certificates option

The optional http_method member specifies the HTTP request method and must have one of the following values:

Job HTTP request method values

Value	Description
get	HTTP GET request
post	HTTP POST request
put	HTTP PUT request

The optional http_headers member specifies additional HTTP headers for HTTP jobs and must be a JSON object with key-value pairs.

The optional http_query_args member specifies additional HTTP query arguments for HTTP jobs and must be a JSON object with key-value pairs.

The optional validate_ssl member specifies how SSL certificates for HTTP jobs over SSL are validated and must be a JSON boolean true or false value:

Job validate SSL values

• true - SSL certficates are validated and self-signed certificates are not allowed;

• false - self-signed SSL certificates are allowed.

If the type member value is http and the http_method member value is post or put, then the params object can contain the following additional values:

Member	Description
http_content_type	The HTTP body content type
http_body_vars	HTTP body variables
http_raw_body	The raw HTTP body

The optional http_content_type member specifies the content type for HTTP POST and PUT job HTTP request body and must have one of the following values:

Job HTTP content type values

Value	Description
json	application/json
url-encoded	application/x-www-form-urlencoded
zend-server	Compatible with Zend Server

The json content type encodes the content of the http_body_vars in JSON and sets the HTTP request header to "Content-Type: application/json".

The url-encoded content type encodes the content of the http_body_vars in key-value tuples separated by "&", with "=" between the key and the value. The HTTP request header is set to "Content-Type: x-www-form-urlencoded".

The zend-server content type is for backward compatibility with Zend Server Job Queue. The request body is encoded in JSON, but the HTTP request header is set to "Content-Type: application/x-www-form-urlencoded".

The optional http_body_vars member specifies the HTTP body variables as key-value pairs and must be a JSON object.

The optional http_raw_body member specifies the complete HTTP request body and must be a JSON string.

The http_content_type and http_body_vars members are ignored if the http_raw_body member is used.

If the type member value is cli, then the params object must contain the following values:

Value	Description
script	The name of the CLI script

The script member specifies the name of the command-line script to be executed with the full path and optional arguments.

The value of the script member is processed using the following rules:

• Backslash \ characters followed by one of the following characters \, , ", and ' are removed and the following character preserves the literal value of the character; backslashes preceding characters without special meaning are left unmodified;

• Enclosing characters in single ' quotes preserve the literal value of each character within the quotes; a single quote may not occur between single quotes;

• Enclosing characters in double " quotes preserve the literal value of each character within the quotes, with the exception of \; a double " quote may be quoted within double quotes by preceding it with a backlash;

If the type member value is cli, then the parameters object CAN contain the following additional values:

Value	Description
env	Environment variables for the CLI job
nodes	Regular expression specifying node names

The optional env member specifies environment variables for command-line script as key-value pairs and must be a JSON object.

The optional nodes member specifies a regular expression for node names on which the command-line script is allowed to run. If the nodes member is omitted, then the command-line script is executed only on the machine where the ZendHQ daemon process is running.

Job default values from the queue are used for all the missing elements.

Example

Add a HTTP job to the queue "feeds" with relative execution time +2 minutes from now:

Client:

{
  "id":5, "method": "jq.add_job", "params": 
  {
    "queue": {"name": "feeds"}, 
    "type": "http",
    "url": "https://zend.com/JobQueueTask.php",
    "schedule": { "date_time": "+02:00" }
  }
}

Server:

{
  "id": 5,
  "result": 5
}

jq.update_job method

Modifies an existing job in the Job Queue.

One-time jobs can be modified only before they are executed. Recurring jobs can be modified any time, but if a task is already running, then that task is not changed.

Triggers the "jq.job_status" notification event.

Request

Member	Description
method	Fixed string "jq.update_job"
params	JSON object with method parameters

The params member must contain the following values:

Value	Description
id	ID value of the job

Any additional members specify changed values. See the jq.add_job method for members details. Members not in the params object are left unchanged.

Response

The result member contains the ID value of the updated job.

Example

Change the recurring cron schedule for a job with the ID value 12:

Client:

{
  "id": 4, "method": "jq.update_job",
  "params": {"id": 12, "schedule": {"cron": "0 */3 * * * *"} }
}

Server:

{"id":4,"result":12}

jq.delete_job method

Deletes a job from the Job Queue. The job is marked deleted and moved to the history.

Triggers "jq.job_status", "jq.job_finished" and "jq.queue_status" notification events.

Request

Member	Description
method	Fixed string "jq.delete_job"
params	JSON object with method parameters

The params member must contain the following values:

Value	Description
id	ID value of the job

Response

The result member contains the fixed string "OK".

Example

Delete a job with the ID value 12:

Client:

{"id" :4, "method": "jq.delete_job", "params": {"id" :12}}

Server:

{"id":4,"result":"OK"}

jq.get_jobs method

Returns a list of all the scheduled jobs in all the queues or in a specific queue.

Request

Member	Description
method	Fixed string "jq.get_jobs"
params	Optional JSON object with method parameters

The params member CAN contain the following values:

Value	Description
queue	Queue identifier

Response

The result member contains a JSON array with jobs in the “native” execution order grouped by queues.

Job object

The Job Queue job object contains the following values:

Value	Description
id	A numeric value uniquely identifying the job
name	Optional name of the job
type	Type of the job
queue	Queue identifier
priority	Job priority value
scheduled_time_sec	Scheduled execution time as UNIX time (seconds since the EPOCH)
status	Job status value
recurring	Optional JSON boolean true value identifying recurring jobs

Job status values

Value	Description
created	Job is created, but not scheduled yet
scheduled	Job is scheduled and waiting for the scheduled execution time
waiting-on-parent	Job has a predecessor, which is not executed yet
running	Job is being executed
suspended	Job is suspended
timeout	Job timed out
failed-no-worker	Job failed due to no worker
failed-worker-error	Job failed due to worker error
deleted	Job is deleted
completed	Job is successfully completed
unknown	Job status is unknown due to an interruption

Example

Get all the scheduled jobs in the queue "feeds":

Client:

{"id":4,"method":"jq.get_jobs","params":{"queue":{"name":"feeds"}}}

Server:

{
  "id": 4, "result": [
  { "id": 3, "priority": "normal", "queue": { "id": 2, "name": "feeds" },
    "scheduled_time_sec": 1677660955, 
    "status": "scheduled",
    "type": "http"
  },
  { "id": 4, "priority": "normal", "queue": { "id": 2, "name": "feeds" },
    "recurring": true,
    "scheduled_time_sec": 1677661020,
    "status": "scheduled",
    "type": "http"
  }
  ]
}

jq.get_job method

Returns job details.

Request

Member	Description
method	Fixed string "jq.get_job"
params	JSON object with method parameters

The params member must contain the following values:

Value	Description
id	ID value of the job

Response

The result member is a JSON object with the job details and contains the following members:

Member	Description
id	ID value of the job
name	Optional name of the job
queue	Queue identifier
priority	Priority of the job
scheduled_time_sec	Optional scheduled execution time as UNIX time (seconds since the EPOCH)
status	Job status value
type	Type of the job
predecessor	Optional predecessor job ID value
recurring	Optional JSON boolean true value identifying a recurring job
schedule	Optional JSON object with the schedule
creation_time_sec	Job creation time as UNIX time (seconds since the EPOCH)
timeout	Job timeout value in seconds
max_retry_count	Maximum number of retries
retry_count	Optional retry count
retry_delay	Delay in seconds between retries
persist	Persist job option
persist_output	Persist job output option
url	Optional request URL for HTTP jobs
http_method	Optional HTTP request method for HTTP jobs
http_content_type	Optional HTTP content type for HTTP jobs
http_raw_body	Optional raw HTTP body for HTTP jobs
http_body_vars	Optional HTTP body variables for HTTP jobs
http_headers	Optional HTTP request headers for HTTP jobs
http_query_args	Optional HTTP request query arguments for HTTP jobs
validate_ssl	Optional validate SSL option for HTTP jobs
script	Optional command-line script for CLI jobs
env	Optional environment variables for CLI jobs

Notice that the optional schedule member can only contain unix_time or cron values.

Example

Get job details for a job with the ID value 4:

Client:

{"id": 4, "method": "jq.get_job", "params": {"id": 4}}

Server:

{
    "id": 4,
	"result": {
		"creation_time_sec": 1677660895,
		"http_body_vars": { "bar": "baz","foo": "bar","forty-two": 42 },
		"http_content_type": "json",
		"http_headers": {
			"Accept": "application/json",
			"Authorization": "token 1234",
			"Connection": "close",
			"Content-Type": "application/vnd.jq+json",
			"User-Agent": "ZendHQ Job Queue/1.3.0",
			"X-Zend-Job-Timeout": "60"
		},
		"http_method": "POST",
		"http_query_args": { "sort": "asc" }, 
		"id": 4, "max_retry_count": 3, "persist": false,"persist_output": "no", "priority": "normal", 
		"queue": {"id": 2, "name": "feeds"},
		"recurring": true, "retry_delay": 1,
		"schedule": {"cron": "0 */3 * * * *"},
		"scheduled_time_sec": 1677663360, "status": "scheduled", "timeout": 60,	"type": "http",
		"url": "https://zend.com/JobQueueTask.php",
		"validate_ssl": false
	}
}

jq.get_job_history method

Returns a list of completed tasks. Completed tasks are executed jobs that were either successful or failed due to an

error. The returned list of tasks is in the reverse task ID value order starting with the latest task.

Request

Member	Description
method	Fixed string "jq.get_job_history"
params	Optional JSON object with method parameters

The params member CAN contain the following values:

Value	Description
count	Maximum number of returned tasks (defaults to 50)
last_id	ID value of the last seen task for implementing pagers
filter	Task filter as a JSON object

The optional count member can be used to limit the number of returned tasks.

The optional last_id member can be used to implement pagers by providing the last seen smallest task ID value.

The optional filter member can be used to filter tasks and can contain the following members:

Member	Description
queue	Only tasks from the specified queue
recurring	Only recurring or only one time jobs
job_id	Only tasks with the specific job ID value
status	Only tasks with the specific status

The optional queue member can be used to return only tasks from the specified queue.

The optional recurring member must have a JSON boolean true or false value. If set to true, returns only recurring job tasks. If set to false, returns only one time job tasks.

The optional job_id member can be used to return only specific job tasks.

The optional status member can be used to return only tasks with the specified status and can have one of the following values:

Value	Description
succeeded	Only tasks that were completed successfully
failed	Only tasks that failed
deleted	Only deleted tasks
unknown	Only tasks that have unknown status due to interruption

Response

The result member is a JSON array with tasks, which contain the following values:

Value	Description
id	The ID value of the task
job_id	The ID value of the job
name	Optional name of the job
type	Type of the job
queue	Queue identifier
status	Status of the task
recurring	Optional JSON boolean true value identifying a recurring job
retry_count	Optional number of retries used to reach the completion status
completion_time_sec	Optional completion time as a UNIX time (seconds since the EPOCH)

Example

Get the list of completed tasks in the queue "feeds":

Client:

{"id":7,"method":"jq.get_job_history","params":{"queue":{"name":"feeds"}}}

Server:

{
  "id": 7,
  "result": [{
    "completion_time_sec": 1677668580, "id": 35, "job_id": 4,
    "queue": {"id": 2, "name": "feeds" },
    "recurring": true,"status": "completed","type": "http"
  },
  {
    "completion_time_sec": 1677668400,"id": 34,"job_id": 4,
    "queue": {"id": 2,"name": "feeds"},
    "recurring": true,"status": "completed","type": "http"
  }]
}

jq.get_task method

Return individual task details.

Request

Member	Description
method	Fixed string "jq.get_task"
params	JSON object with method parameters

The params member must contain the following values:

Value	Description
id	The ID value of the task

Response

The result member a JSON object with the task details and contains the following values:

Member	Description
id	The ID value of the task
job_id	The ID value of the job
name	Optional name of the job
type	Type of the job
queue	Queue identifier
status	Status of the task
recurring	Optional JSON boolean true value identifying a recurring job
retry_count	Optional number of retries used to reach the completion status
creation_time_sec	Job creation time as UNIX time (seconds since the EPOCH)
start_time_sec	Optional time when task execution started as UNIX time (seconds since the EPOCH)
completion_time_sec	Optional completion time as a UNIX time (seconds since the EPOCH)
output	Optional output of the task
url	The URL of the HTTP job
http_method	The HTTP request method of the HTTP job
http_query_args	Optional HTTP query arguments as an encoded string
http_headers	Optional HTTP query headers as an encoded string
http_body	Optional HTTP request body as an encoded string
script	The script name of the CLI job
nodes	Optional node names where the task was run
env	Optional environment variables for the CLI job as an encoded string

Example

Get the details of a task:

Client:

{"id":8,"method":"jq.get_task","params":{"id":34}}

Server:

{
"id": 8,
"result": {
   "completion_time_sec": 1677668400,"creation_time_sec": 1677660895,
   "http_body": "{\"bar\":\"baz\",\"foo\":\"bar\",\"forty-two\":42}",
   "http_method": "POST",
   "http_query_args": "sort=asc",
   "id": 34,"job_id": 4,
   "output": "HTTP/1.1 200 OK\r\nServer: nginx\r\nDate: Wed, 01 Mar 2023 11:00:00 GMT\r\nContent-Type: 
text/html; charset=UTF-8\r\nTransfer-Encoding: chunked\r\nConnection: close\r\nStrict-Transport-Security: 
max-age=15552000; includeSubDomains\r\n\r\n<p>query arguments: sort=asc</p><p>working...done!</p> 
   "queue": {"id": 2,"name": "feeds"},
   "recurring": true,
   "start_time_sec": 1677668400,
   "status": "completed",
   "type": "http",
   "url": "https://zend.com/JobQueueTask.php"
 }
}

jq.queue_status event

The jq.queue_status notification event is sent out every time the status of a queue changes:

• Queue added

• Queue modified

• Queue deleted

• Number of scheduled jobs changed

• Queue suspended

• Queue activated

The params member contains the following values:

Value	Description
id	ID value of the queue
name	Name of the queue
jobs_count	Number of scheduled jobs in the queue
priority	Queue priority value
status	Queue status value
default	Optional JSON boolean true value identifying the default queue

Example

Server:

{
   "event": "jq.queue_status",
   "params": { 
     "default": true, "id": 1, "jobs_count": 3, "name": "__default__",
     "priority": "normal", "status": "suspended"
   }
}

jq.job_status event

The jq.job_status notification event is sent out every time the status of a job changes:

• Job added

• Job modified

• Job deleted

• Job scheduled

• Job started execution

• Job execution finished

The params member contains the following values:

Value	Description
id	ID value of the job
name	Optional name of the job
type	Type of the job
queue	Queue identifier
priority	Job priority value
scheduled_time_sec	Scheduled execution time as UNIX time (seconds since the EPOCH)
status	Job status value
recurring	JSON boolean true value identifying recurring jobs

Example

Server:

{
  "event": "jq.job_status",
  "params": {
    "id": 4,"priority": "normal",
    "queue": {"id": 2,"name": "feeds"},
    "recurring": true, "scheduled_time_sec": 1677669840,
    "status": "running", "type": "http"
 }
}

jq.job_finished event

The jq.job_finished notification event is sent out when a job is removed from the queue and moved to the history:

• one-time job has finished execution; or

• one-time or recurring job is deleted.

The params member contains the following values:

Value	Description
id	ID of the job

Example

Server:

{ "event": "jq.job_finished", "params": { "id": 6 } }

jq.task_finished event

The jq.task_finished notification event is sent out when a task execution is finished.

The params member contains the following values:

Value	Description
id	The ID value of the task
job_id	The ID value of the job
name	Optional name of the job
type	Type of the job
queue	Queue identifier
status	Status of the task
recurring	Optional JSON boolean true value identifying a recurring job
retry_count	Optional number of retries used to reach the completion status
start_time_sec	Start time as a UNIX time (seconds since the EPOCH)
completion_time_sec	Completion time as a UNIX time (seconds since the EPOCH)

Example

Server:

{
  "event": "jq.task_finished",
  "params": {
    "completion_time_sec": 1677670316,
    "id": 46,"job_id": 6,
    "queue": {"id": 2,"name": "feeds"},
    "retry_count": 3, "start_time_sec": 1677670315,
    "status": "failed-worker-error", "type": "http"
  }
}