Application Metrics for HealthShare

One of the great features in InterSystems IRIS is Monitoring InterSystems IRIS using REST API.  This enables every InterSystems HealthShare instance with the ability to use a REST interface to provide statistics about the InterSystems HealthShare instance.  This feature includes information about the InterSystems IRIS instance with many out of the box statistics and metrics.

You also have the ability to create application level statistics and metrics.

User Story:  As a large organization, we want to know how many people (patients or members) and how many documents we are managing in our HealthShare solution to help us understand our population being served.

Note: This example was done in InterSystems HealthShare 2023.1.

First, in the InterSystems HealthShare HSREGISTRY namespace, we are going to create a class (HS.Local.HSREGISTRY.HSMetrics.cls) to capture the information for the new application metric.

Code for the class:

Class HS.Local.HSREGISTRY.HSMetrics Extends %SYS.Monitor.SAM.Abstract
{
Parameter PRODUCT = "myHS";

/// Collect counts for Patients and Documents
Method GetSensors() As %Status
    {
                &sql(SELECT COUNT(*) INTO :tPatCount FROM HS_Registry.Patient)
                do ..SetSensor("HSPatientCount",tPatCount,"HSREGISTRY")
                &sql(SELECT COUNT(*) INTO :tDocCount FROM HS_Registry.Document)
                do ..SetSensor("HSDocumentCount",tDocCount,"HSREGISTRY")
               
                return $$$OK
      }
}

The important features of this class include:

• The name of the class begins with “HS.Local”, which is mapped to the HSCUSTOM namespace and contains custom code.  This code will not get overwritten during upgrades.
• The name of the class includes “HSREGISTRY”, this let’s us identify which namespace we are gathering these statistics. In the future, we can gather statistics in other namespaces and this naming convention allows us to differentiate and know where this is collection is run.
• This class inherits from “%SYS.Montior.SAM.Abstract”, which it needs to work with the existing REST API.
• There is a product name defined as “myHS”, this could be your company name or a line of business or anything you would like to differentiate these statistics.  This product name will appear as a prefix in the REST API output of this new metric.
• The method “GetSensors()” is used to collect the statistics.
• We use SQL to get the counts of the data.  It is important to understand how long particular SQL statements takes to run as it will affect performance of the returned API.
• When we call “SetSensor()” we are calling with the parameters:
  • Name of the metric
  • The value of the metric
  • An identifier (in this case, the namespace so we know where we got the data) of this metric.

After we have saved and compiled this class, we need to include our new class into the /metrics configuration.

From a terminal session on the InterSystems HealthShare instance with HSREGISTRY namespace:

• USER> zn “%SYS”

• %SYS> write ##class(SYS.Monitor.SAM.Config).AddApplicationClass("HS.Local.HSREGISTRY.HSMetrics", "HSREGISTRY")

These commands tell us to run the class we created in the HSREGISTRY namespace when we call the REST API.

Next, we must ensure that web application /api/monitor will have access to both the code and the data.

We need to add the following application roles to the web application:

• %DB_HSCUSTOM (to read the class)
• %DB_HSREGISTRY (to read the data)

Screen Shot from System Management Portal:

Now, when you call the REST API (http://<baseURL>/api/monitor/metrics), you will see your metrics:

I hope this helps inspire you to create your own application metrics within InterSystems HealthShare using this exciting InterSystems IRIS feature.