Overview

In many settings, a single organization or entity may support a network of OpenMRS server installations across a wide geography.  Supporting these installations can be a tremendous challenge, particularly when connectivity is limited, and it is often unclear which installations are functioning properly, in use, and deployed consistently.  This module aims to provide a mechanism for such a support team to have greater visibility into the actual systems in use, in order to be better able to make data driven decisions.

Additional overview information may be found in the README on github.

Installation

Where to get it

This module can be downloaded from the module repository.

Developers may build this module from source directly, or may leverage it's artifacts as found in the OpenMRS maven repository.

Dependencies

• OpenMRS Core:  1.9.8+
• App Framework:  2.4+
• App UI:  1.3+
• UI Commons:  1.8+
• UI Framework: 3.4+
• Web Services REST:  2.12+

NOTE:  It is likely that this documentation will not keep up with dependency versioning.  For the latest versions requirements, please consult the module repository, or the root pom.

Connection with a Parent instance

There are two ways to configure a server to connect to a parent server to send it reports.

1. If the sync module is running, and you would like to use the same URL and credentials as are defined for submitting into the Sync parent server, no further configuration is needed
2. Otherwise, you must specify these credentials within your openmrs-runtime.properties file as such:
   
   • emrmonitor.parentUrl=http://localhost:8081/openmrs
   • emrmonitor.parentUsername=admin
   • emrmonitor.parentPassword=test

Once a child server is configured with valid credentials to the parent server, everything else is handled automatically.  No manual registration of servers is required.

Configuration

Frequency of Reports

By default, the module will record one Report per day for the current Server, or as close as possible to that as it can.  This is the recommended setting.  You can configure this to be more frequent or less frequent with the setting named emrmonitor.minutesBetweenReports

Metrics and how they are calculated

Within a Report, the module will record multiple Metrics.  Metrics are generated and recorded by constructs called Metric Producers.  The supplied Metric Producers can be viewed here.  You can disable one or more of these Metric Producers by supplying a comma-separated list of Metric Producer namespaces to the setting named emrmonitor.disabledMetricProducers

Additional or alternative Metric Producers can be easily added by developers by simply implementing the MetricProducer interface and exposing your class as a Spring component.

There is also a special Configurable Metric Producer that supports implementation-defined metrics added at runtime, which is designed to enable implementers who are not familiar with module development, but can author SQL or do other scripting, to customize what is produced. This works by iterating over and executing any files located in the {application_data_dir}/configuration/emrmonitor directory. The name of any file in this directory will represent the "namespace" of the metrics that it produces. The following files are supported:

1. SQL files: Any file with a ".sql" extension will be executed.

   • If a single value is returned by the query, then the metric is the filename and the value is the result
   • If multiple rows with a single column is returned, then the value is a comma separated list
   • If multiple columns are returned, then all but the last column are appended to the metric name, and the last column is the value

2. Shell Scripts: Any file with a ".sh" extension will be executed.

   • If multiple lines of output are returned and each is in the format of key=value, then the key will be considered part of the metric, and the value the value
   • Otherwise, the full contents of output will be the value of a single metric