Create Custom Prometheus Metrics

This example shows how to create custom Prometheus^® metrics on a MATLAB^® Production Server™ instance and retrieve them using the metrics service. To create custom metrics, use the prodserver.metrics.setGauge and prodserver.metrics.incrementCounter functions in the deployed MATLAB function. After you execute the deployed function, query the Metrics Service (MATLAB Production Server) to retrieve the custom metrics.

The example assumes that there is an on-premises server running at http://localhost:9910 managed using the command line.

Write MATLAB Code to Create Custom Metrics

Write a MATLAB function that calls the proprodserver.metrics.setGauge and prodserver.metrics.incrementCounter functions to create Prometheus metrics of type gauge and counter, respectively. proprodserver.metrics.setGauge and prodserver.metrics.incrementCounter do not return any output.

The following test_metrics function only creates example metrics. In practice, the MATLAB programmer, in consultation with the server administrator, creates metrics related to the deployed application that help instrument the deployed MATLAB code.

function rc = test_metrics()
tic
prodserver.metrics.incrementCounter("test_function_execution_count",1)
toc
prodserver.metrics.setGauge("test_timer_seconds",toc)
rc = 0;
end

Deploy MATLAB Function to Server

Package the function test_metrics.m into a deployable archive called test_metrics and deploy it to the server.

For details on creating and starting a server, see Create Server Instance Using Command Line (MATLAB Production Server) and Start Server Instance Using Command Line (MATLAB Production Server).

For details on creating a deployable archive and deploying it to the server, see Create Deployable Archive for MATLAB Production Server (MATLAB Production Server) and Deploy Archive to MATLAB Production Server (MATLAB Production Server).

Enable Metrics on Server

Enable the metrics service on the server by editing the server configuration file, main_config. In main_config, uncomment the --enable-metrics property. Restart the server for the changes to take effect.

Execute Deployed Function

Using the language of your choice, write a client application to execute the deployed function. This example uses a cURL command on a Windows^® terminal to send requests to the server. For more information on constructing requests, see JSON Representation of MATLAB Data Types (MATLAB Production Server).

The following command executes the function test_metrics deployed to a server running at http://localhost:9910. Executing the function increments the test_function_execution_count metric by 1 and sets the test_timer_seconds metric to a varying number.

curl -v -H Content-Type:application/json -d '{"nargout":0,"rhs":[]}' http://localhost:9910/test_metrics/test_metrics

Query Metrics Service to Retrieve Custom Metrics

Custom metrics are registered on the server after a client calls the deployed MATLAB function. To retrieve the metrics, use the GET Metrics (MATLAB Production Server) API by accessing the following URL in a web browser. In practice, a Prometheus server scrapes the metrics HTTP/HTTPS endpoint.

http://localhost:9910/api/metrics

The output of the metrics service contains information about server metrics. It also contains the test_function_execution_count and test_timer_seconds custom metrics, along with the name of the deployable archive, test_metrics, that generates the metrics.

# 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_2"} 0.0194095

Since the metric type of test_function_execution_count is a counter, its value increases by 1 every time you execute the deployed function and query the metrics service. Since the metric type of test_timer_seconds is a gauge, its value can increase or decrease every time you execute the deployed function and query the metrics service.