Supporting application monitoring

Prerequisites: Gateway Application Metrics

The Gateway Framework supports the use of Micrometer to expose metrics to different backend systems. It includes the Micrometer core library and provides an option in the Gateway Application to supply MeterRegistry to the framework.

To expose application metrics, developers must include a monitoring tool-specific Micrometer registry library in the application’s classpath to supply the MeterRegistry to the framework. The framework uses the MeterRegistry to expose default metrics related to publishing messages to Diffusion and external systems, any state of the application, and its connection to Diffusion.

A set of metrics is defined by the framework for each service instance added in the application. Such metrics contain a tag with service as the key and the name of the service as its value. Developers can also use the MeterRegistry to specify any additional application/service-specific metrics. The service-specific metrics should contain a tag with service as the key and the name of the service as its value. This ensures that when a service is removed, all metrics associated with the service name tag will be removed.

Integrating Gateway metrics API in the Gateway application

default-metrics-library is available as a pre-built helper library to ease the following steps to expose the Prometheus and JMX metrics.

To integrate Gateway Metrics API in the Gateway application, follow these steps:

  1. Add a monitoring tool-specific Micrometer registry library as a dependency in the application.

    Example 1. Including Micrometer registry for JMX
        <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-registry-jmx</artifactId>
        <version>1.8.1</version>
    </dependency>

  2. Override method initializeGatewayMeterRegistry in the GatewayApplication interface to supply Micrometer’s MeterRegistry to be used in the application.

        @Override
    public GatewayMeterRegistry initializeGatewayMeterRegistry(
            Map<String, Object> globalApplicationConfiguration) {
        JmxMeterRegistry meterRegistry =
            new JmxMeterRegistry(s -> null, Clock.SYSTEM);
        return new GatewayMeterRegistryImpl(meterRegistry);
    }

    The framework supplies the configuration defined in the application block in the global section into initializeGatewayMeterRegistry method. For example, from the following global configuration, defined in the configuration file for the application, the configuration block in the application section will be passed as a Map in the method:

      "global": {
    "framework": {
      "threadPoolSize": 10,
      "mode": "DYNAMIC",
      "metrics": {
        "enabled": true
      }
    },
    "application": {
      "prometheus": {
        "path": "/metrics",
        "port": 8089
      },
      "jmx": true
    }
  }
}

    The supplied map containing the required configuration to expose the metrics can be used to initialize the MeterRegistry to expose metrics to any required system.

    The ApplicationContext instance passed into the GatewayApplication.initialize(ApplicationContext applicationContext) method includes an isMetricsEnabled method that can be checked before wiring up metrics related configuration and classes.

  3. If required, expose any application-specific metrics using Meter(such as, Counter, Timer) of Micrometer in service handlers.

        private Counter errorCounter =
        meterRegistry
            .counter(
                "error.total",
                TAG_KEY_SERVICE,
                serviceDefinition.getServiceName());
    ...
    ...
    errorCounter.increment();
The Framework provides a few utility methods which can be used to create/append tags for the meters. See GatewayMeterRegistry for more details.
For service specific metrics, service names must be used as tag, so that metrics are specified for each service and can be easily analyzed and managed.

With just the first two steps, several metrics will be exposed, including the ones related to JVM and system status. A user can disable any specific metrics, in the configuration, if not required.

See this page to understand, how users would configure application metrics and to get familiar with metrics exposed out-of-the-box by the framework.

See ExampleGatewayApplication for example of exposing Prometheus metrics.

To ease exposing the Prometheus and JMX metrics in the application, there is a pre-built helper library that can be used to initialize the MeterRegistry stated in step 2 and spin up an HTTP server to expose Prometheus metrics. See next page for details on how to use the library.