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 (default of 10091, but based on 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

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, and the default token is zendphp.

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

Example

Client:

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

Server:

{"id":1,"result":{"sid":"O7S4YAAAAACYFLMnhBsNXgAAAIM","valid_until":1622717499}}

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

Example

Client:

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

Server:

{"id":1,"result":{"sid":"O7S4YAAAAACYFLMnhBsNXgAAAIM","valid_until":1622717499}}

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

Example

Client:

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

Server:

{"id":1,"result":{"sid":"nIa4YAAAAADf8v8b1RyiQAAAACA","valid_until":1622705820}}

Namespace "conf"

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

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.

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.

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

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.

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

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

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
request Optional request data object
source PHP code reference object
error Optional error data object
stack_trace  
custom Optional custom event data object
variables Optional $_SERVER, $_REQUEST, etc
actions Optional, actions taken

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

source

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

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 the following values:

Member Description
issue_id The ID of the issue

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
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 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
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
source PHP code reference object
error Optional error data object
stack_trace  
custom Optional custom event data object
variables Optional _SERVER, _REQUEST, etc
actions Optional, actions taken

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

Response

The result member contains the fixed string "OK".

Example

Client:

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

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 tace
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

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,
	   "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 tace
time_sec UNIX time of the trace
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)

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 tace
status Fixed string "stored"
time_sec UNIX time of the trace
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,
		"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

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",
	}
}