Monitoring InterSystems IRIS Using REST API

Copy link to this sectionMetric Descriptions

The metrics are returned in a text-based format, described in the Exposition Formats page of the Prometheus documentation (https://prometheus.io/docs/instrumenting/exposition_formats/). Each metric is listed on a single line with only one space, which separates the name from the value.

InterSystems IRIS metrics are listed in the table below. Metric names with a label appear here with line breaks to improve readability.

Copy link to this sectionCreate Application Metrics

To add custom application metrics to those returned by the /metrics endpoint:

1. Create a new class that inherits from %SYS.Monitor.SAM.Abstract.

2. Define the PRODUCT parameter as the name of your application. This can be anything except for iris, which is reserved for the InterSystems IRIS metrics.

3. Implement the GetSensors() method to define the desired custom metrics, as follows:

   • The method must contain one or more calls to the SetSensor() method. This method sets the name and value for an application metric. The values should be integers or floating point numbers to ensure compatibility with Prometheus and InterSystems SAM.

     You can optionally define a label for the metric, though if you do, you must always define a label for that particular metric.

     Note:

     For best practices when choosing metric and label names, see Metric and Label Naming in the Prometheus documentation (https://prometheus.io/docs/practices/naming/).

   • The method must return $$$OK if successful.

   Important:

   A slow implementation of GetSensors() can negatively impact system performance. Be sure to test that your implementation of GetSensors() is efficient, and avoid implementations that could time out or hang.

4. Compile the class. An example is shown below:

   /// Example of a custom class for the /metric API
   Class MyMetrics.Example Extends %SYS.Monitor.SAM.Abstract
   {
   
   Parameter PRODUCT = "myapp";
   
   /// Collect metrics from the specified sensors
   Method GetSensors() As %Status
   {
      do ..SetSensor("my_counter",$increment(^MyCounter),"my_label")
      do ..SetSensor("my_gauge",$random(100))
      return $$$OK
   }
   
   }

   Copy code to clipboard

5. Use the AddApplicationClass() method of the SYS.Monitor.SAM.Config class to add the custom class to the /metrics configuration. Pass as arguments the name of the class and the namespace where it is located.

   For example, enter the following in the Terminal from the %SYS namespace:

   %SYS>set status = ##class(SYS.Monitor.SAM.Config).AddApplicationClass("MyMetrics.Example", "USER")
   
   %SYS>w status
   status=1

   Copy code to clipboard

6. Ensure that /api/monitor web application has the necessary Application Roles to access the custom metrics. For details on how to edit application roles, see Edit an Application: The Application Roles Tab.

   This step grants /api/monitor access to the data needed for the custom metric. For example, if the custom metric class is located in the USER database (protected by the %DB_USER resource), grant /api/monitor the %DB_USER role.

7. Review the output of the /metrics endpoint by pointing your browser to http://<instance-host>:52773/api/monitor/metrics (where 52773 is the default WebServer port). The metrics you defined should appear after the InterSystems IRIS metrics, such as:

   [...]
   myapp_my_counter{id="my_label") 1
   myapp_my_gauge 92
   

The /metrics endpoint now returns the custom metrics you defined. The InterSystems IRIS metrics include an “iris_” prefix, while your custom metrics use the value of PRODUCT as a prefix.