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 that returns information about client requests, the time and memory that the server takes to execute these requests, and optional custom metrics

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.

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:

Key	Value
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:

Key	Value
archiveSchemaVersion	JSON string representing the version number of the archive schema Example: 1.1.0
archiveUuid	JSON 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
typedefs	JSON 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:

Key	Value
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:

Key	Value
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:

Key	Value
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:

Key	Value
help	JSON string containing the description for the cell array Example: "help": "cell help"
type	cell
elements	JSON array of objects describing each element of the cell array

Each object in elements contains the following fields:

Key	Value
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:

Key	Value
help	JSON string containing the description for the structure Example: "help": "struct help"
type	struct
fields	JSON array of objects describing each element of the structure

Each object in fields contains the following fields:

Name	Description
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"

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 the 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.

Custom Metrics

You can instrument deployed MATLAB code by adding custom metrics specific to your application or request processing. In the deployed MATLAB code, you can create custom Prometheus metrics by using the functions prodserver.metrics.incrementCounter (MATLAB Compiler SDK) and prodserver.metrics.setGauge (MATLAB Compiler SDK). The functions create metrics of Prometheus counter and gauge metric types, respectively.

The server collects the custom metrics when a client calls the deployed MATLAB function. In addition to the default server metrics, the output of the metrics service includes the custom metrics and the name of the deployable archive that created the metrics.

For example, including the following functions in the MATLAB function that you deploy to the server creates custom metrics called test_function_execution_count and test_timer_seconds.

prodserver.metrics.incrementCounter("test_function_execution_count",1);
prodserver.metrics.setGauge("test_timer_seconds",0.421147);

When you query the metrics API after a client calls the deployed function, you see the following output:

# TYPE matlabprodserver_up_time_seconds counter
matlabprodserver_up_time_seconds 16705.3
# TYPE matlabprodserver_queue_time_seconds gauge
matlabprodserver_queue_time_seconds 0
# TYPE matlabprodserver_cpu_time_seconds counter
matlabprodserver_cpu_time_seconds 29.1406
# TYPE matlabprodserver_memory_working_set_bytes gauge
matlabprodserver_memory_working_set_bytes 5.17153e+08
# TYPE matlabprodserver_requests_accepted_total counter
matlabprodserver_requests_accepted_total 7
# 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 7
# TYPE matlabprodserver_requests_failed_total counter
matlabprodserver_requests_failed_total 0
# TYPE matlabprodserver_requests_canceled_total counter
matlabprodserver_requests_canceled_total 0
# TYPE test_function_execution_count counter
test_function_execution_count{archive="test_metrics_2"} 1
# TYPE test_timer_seconds gauge
test_timer_seconds{archive="test_metrics"} 0.421147

The output contains the test_function_execution_count and test_timer_seconds custom metrics, and the name of the deployable archive, test_metrics, that generates the metrics.

For a detailed example, see Create Custom Prometheus Metrics.