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