Main Content

RESTful API for Discovery and Diagnostics

The MATLAB® Production Server™ RESTful API for discovery and diagnostics consists of the following APIs:

  • A discovery service that provides information about MATLAB functions deployed on a server

  • A health check API that lets you know if the server is available to process requests.

  • A server metrics service returns information about client requests, and time and memory that the server takes to execute these requests.

The health check and the discovery service return responses in JSON format. The metrics service returns data in Prometheus metrics format.

Characteristics of RESTful API

The MATLAB Production Server RESTful API for discovery and diagnostics uses the HTTP request-response model for communication with MATLAB Production Server. This model includes request methods, response codes, message headers, and message bodies. The RESTful API for discovery and diagnostics has the following characteristics:

  • The HTTP GET method forms the primary mode of communication between client and server.

  • Unique Uniform Resource Identifiers (URIs) identify the resources that the server creates.

  • Since requests to the server use the GET method, the requests do not have a message body and you do not have to set the Content-Type header in the request.

  • The message body of the response contains information specific to a request such as information about functions deployed to the server, server health status, or server metrics.

Discovery Service

Use the discovery service to learn about MATLAB functions that you deploy to the server. The discovery service returns information about the deployed MATLAB functions as a JSON object. The object is a multilevel nested structure and at a high level displays the discovery schema version and a list of deployed archives. Each archive contains information about the deployed MATLAB functions and their function signatures.

To use the discovery service, you must enable the discovery service on the server by setting the --enable-discovery property in the main_config server configuration file.

To get useful information when using the discovery service, you must include a JSON file containing function signatures of the MATLAB functions that you want to deploy when creating the deployable archive. For information on how to create a deployable archive, see Create Deployable Archive for MATLAB Production Server. For information about creating the JSON file containing function signatures, see MATLAB Function Signatures in JSON.

Call the discovery service using GET Discovery Information.

The response from the server is a JSON object.

Example of a response to the GET discovery information request.

JSON Response Object

The JSON response object contains a version number for the discovery schema and a list of deployed archives. The response object contains the following fields:

KeyValue
discoverySchemaVersion

JSON string containing the version number for the discovery schema in the format <major#>.<minor#>.<patch#>, where each number is a nonnegative integer.

Example value: 1.0.0

archives

JSON object containing a list of all deployed archives.

archives JSON Object

The archives object contains a list of all deployed archives. Each object in this list is a JSON object whose key is the name of the deployed archive, for example, <Name of the CTF archive>, and whose value is a JSON object that has the following fields:

KeyValue
archiveSchemaVersion

JSON string representing the version number of the archive schema.

Example: 1.1.0

archiveUuidJSON string representing a unique identifier for the archive.
matlabRuntimeVersion

JSON string representing the MATLAB Runtime version.

Example: 9.9.0

functions

JSON object containing a list of functions in the deployed archive.

typedefsJSON object containing a list of cell arrays or structures used as input or output arguments to deployed functions.

functions JSON Object

The functions object contains a list of nested JSON objects, where each nested object corresponds to a MATLAB function in the deployed archive.

Each function object has the name of the deployed function as its key, for example, <MATLAB_function_name1>, and a JSON object as its value. The JSON object contains a signatures key whose value is an array of JSON objects that contain information about the MATLAB function signatures.

Each object in the signatures array contains the following fields:

KeyValue
help

Name of input parameter.

Example: "name": "input1"

inputs

Array of JSON objects containing information about input arguments

outputs

Array of JSON objects containing information about output arguments

Each object in the inputs array contains the following fields:

KeyValue
name

Name of input parameter.

Example: "name": "input1"

mwtype

MATLAB data type.

Example: "mwtype": "double"

mwsize

Size of data.

Example: "mwsize": ["2,3"]

help

Description for input arguments.

Example: "help": "input1 description"

Each object in the outputs object contains the following fields:

KeyValue
name

Name of output parameter.

Example: "name": "output1"

mwtype

MATLAB data type.

Example: "mwtype": "double"

mwsize

Size of data.

Example: "mwsize": ["2,3"]

help

Description for output parameters.

Example: "help": "output1 description"

typedefs JSON Object

The response contains the typedefs object only if deployed functions contain cell arrays or structures as input or output arguments.

If deployed functions contain cell arrays as input or output arguments, the typedefs object contains nested objects whose key is the name of the cell array, for example, <homogeneous_cell_name>, and the corresponding value contains an object with information about the cell array.

Each object in the <cell_array_name> object contains the following fields:

KeyValue
help

JSON string containing the description for the cell array.

Example: "help": "cell help"

typecell
elements

JSON array of objects describing each element of the cell array.

Each object in elements contains the following fields:

KeyValue
name

Name of cell element.

Example: "name": "a"

type

Data type of element.

Example: "type": "double"

size

Size of array.

Example: "size": ["2,3"]

help

Description of cell element.

Example: "help": "Operand a"

If deployed functions contain structure arrays as input or output arguments, the typedefs object contains nested objects whose key is the name of the structure, for example, <struct_name>, and the corresponding value contains an object with information about the structure.

Each object in the <struct_name> object contains the following fields:

KeyValue
help

JSON string containing the description for the structure.

Example: "help": "struct help"

typestruct
fields

JSON array of objects describing each element of the structure.

Each object in fields contains the following fields:

NameDescription
name

Name of struct field.

Example: "name": "my_field_name"

type

Data type of field value.

Example: "type": "char"

size

Size of struct.

Example: "size": ["2,3"]

help

Description for struct element.

Example: "help": "description for my_field_name"

Health Check

Use the health check API to determine if the server has a valid license and is able to process HTTP requests. The health check classifies the server as healthy or unhealthy depending on whether the server has a valid license and can communicate with the Network License Manager. To check the server health, use GET Server Health.

A server is healthy when it is in one of the following states:

  • The server is operating with a valid license. The server is communicating with the network license manager, and the required number of license keys are checked out.

  • The server has lost communication with the network license manager, but the server is still fully operational and will remain operational until the end of the grace period as specified by the license-grace-period property.

If the health check is successful, the server responds with a 200 OK HTTP status code and a JSON object indicating that the server is healthy.

{
  "status": "ok"
}

When the server is unavailable to process HTTP requests, the health check API returns a 503 Health Check Failed HTTP response code with an empty response body. The health check fails when the server has lost communication with the Network License Manager for a period of time exceeding the grace period. When the server is in this state, it actively attempts to reestablish communication with the license manager. Request processing resumes if the sever is able to reestablish communication with the license manager.

A failed health check does not provide additional information about the cause of failure in the response body. Server administrators can use mps-status to get detailed information about the server status. You must be on the same system as the server to run mps-status.

For more information on licensing, see Manage Licenses for MATLAB Production Server.

Metrics Service

Use the metrics service to retrieve server metrics in Prometheus® metrics format. The metrics service returns information about requests that client applications send to the server, and the time and memory that the server takes to execute the requests. You can use the metrics to monitor the server when working with Kubernetes® and microservices. To call the metrics services, use GET Metrics.

To use the metrics service, you must enable the metrics service on the server by setting the --enable-metrics property in the main_config server configuration file.

A successful response from the server consists of several server metrics in Prometheus counter and gauge metric types. For more information about Prometheus metrics format, see Prometheus Metric Types.

# TYPE matlabprodserver_up_time_seconds counter
matlabprodserver_up_time_seconds 68140.5
# TYPE matlabprodserver_queue_time_seconds gauge
matlabprodserver_queue_time_seconds 0
# TYPE matlabprodserver_cpu_time_seconds counter
matlabprodserver_cpu_time_seconds 18.2188
# TYPE matlabprodserver_memory_working_set_bytes gauge
matlabprodserver_memory_working_set_bytes 1.57426e+08
# TYPE matlabprodserver_requests_accepted_total counter
matlabprodserver_requests_accepted_total 0
# TYPE matlabprodserver_requests_in_queue gauge
matlabprodserver_requests_in_queue 0
# TYPE matlabprodserver_requests_processing gauge
matlabprodserver_requests_processing 0
# TYPE matlabprodserver_requests_succeeded_total counter
matlabprodserver_requests_succeeded_total 0
# TYPE matlabprodserver_requests_failed_total counter
matlabprodserver_requests_failed_total 0
# TYPE matlabprodserver_requests_canceled_total counter
matlabprodserver_requests_canceled_total 0

An error response of 403 Metrics Disabled indicates that the metrics service is not enabled on the server.

See Also

|

Related Topics