HL7 Metric Device

The HL7 metric device is a built-in device designed to let you track metrics related to HL7v2 messages passing through a channel. It utilizes the metrics framework (and Prometheus and Grafana) new in the 16.1 release.

It allows you to track specific field values (or combinations of fields) and visualize the results and trends via a Grafana dashboard. A simple example might be tracking the volume of messages received by Sending Facility (MSH-4) in a channel that receives HL7 from multiple sources.

To use this device, add it to a channel which processes HL7. We’ll start with a simple example which tracks MSH-4.

Open

Click the Add Metric button and fill in the new line as follows:

Open

• Enabled: Is the corresponding metric enabled (disabled metrics are skipped).

• Name: The name of the metric for Grafana/Prometheus. The Name field shouldn’t change once you start ingesting data, as each unique name is treated as a distinct metric.

• Type

  • Value: You are tracking the value of the Expression field. For example, if you want to create a metric which tracks the count of each distinct value of MSH-4.

  • Label: You wish to include the value of the Expression field as a label embedded in each metric of type Value. For example, you wish to track the value of PID-3 by each distinct value of MSH-4. This option lets you include the values of other HL7 fields with each tracked Value. See the previous metrics pages for information about labels.

• Expression: The value which should be tracked. For example, if you wish to track the value of MSH-4, then enter MSH-4. As this is an expression control, you can create your own composite values (for example, MSH-4 + MSH-5, or, MSH-4 + '_foo' etc.).

• Condition: An expression which determines if a metric should run for a specific message. For example, MSH-4 = 'foo' would cause the metric to be evaluated only when the MSH-4 value matches 'foo’. The default is ALWAYS.

• Track Null: If the given Expression evaluates to NULL or EMPTY (for example, the field doesn’t exist in the message) then by default it will be ignored. If you wish to capture this scenario, check this field and enter a value into the Null/Empty Value column which represents the empty value (for example, Missing).

If we start the above channel and process some HL7 messages, no metrics will be written. We must also enable this metric within the Connexion metrics configuration.

Once the Metrics configuration has been updated and the connexion_hl7_message_metrics has been enabled, we can consume this metric within Grafana.

Navigate to Grafana and create a new dashboard and visualization. In the Metrics browser enter connexion_hl7_message_metrics followed by an opening curly brace ({). You should now be prompted to choose from the available labels. For this sample, select the Name label and choose the value entered in the Name column of the HL7 metrics device.

If you have pushed some messages through the channel, you should now have a visualization. The above image shows a Pie Chart with the legend pulling the values from the Value label. You can create as many simple metrics (a row in the above image) as you like, but keep in mind that metrics do consume (minimal) system resources.

Lets add another metric for Patient Sex (PID-8):

And add another visualization in Grafana:

Now let’s switch from having two simple metrics (SendingFacility and PatientSex) and create a compound metric which tracks patient sex by sending facility. To accomplish this, we need to switch the SendingFacility metric from Type Value to Label. Doing this will alter the underlying metrics and SendingFacility will now be included as a label in each Value-type metric.

In Grafana, we can now create the following definition:

Each Label metric you define is included with all Value type metrics (as a label). This lets you create very granular visualizations from your HL7 data sets.

We have added a new type of global: Global HL7 Metric

This global type allows you to define a base set of HL7 metrics and reference one or more global metrics within an HL7 metric device.

Create a global HL7 metric, and define one or more child metrics:

You can reference this global within an HL7 metric device by clicking the global icon and selecting the corresponding name:

This will add the global metric rows to the top of your metrics table, as read-only.