Gateway default metrics library
This library is not part of the Gateway framework library, as not all applications
want to expose the Prometheus or JMX metrics. However, if they do, the default-gateway-metrics
dependency can be simply added in the application and used. If the requirement is
not to expose the Prometheus metrics, follow the steps defined here to expose the application metrics in another backend system.
This library is distributed as a separate JAR from the Gateway framework JAR. Both of them can also be found in the final bundled artifact for the Gateway framework.
The library simply provides methods to initialize the MeterRegistry
of Micrometer
(for the Prometheus and JMX metrics) required to supply to the framework and
starting an HTTP server to expose the Prometheus metrics.
By default, only Prometheus metrics are enabled.
JMX metrics can be enabled via the configuration
supplied in the MetricsHandle.initializeMeterRegistry method.
Below are the steps to use this library.
-
Include following dependency in the application’s
pom.xml
file.<dependency> <groupId>com.diffusiondata.gateway</groupId> <artifactId>gateway-default-metrics</artifactId> <version>2.2.0_RC1</version> </dependency>
This dependency contains the Micrometer registry libraries for JMX and Prometheus. Hence, they do not need to be added separately.
-
Initialize an instance of
MetricsHandler
to initialize theMeterRegistry
and start the Prometheus metrics as required.private final MetricsHandler metricsHandler = MetricsHandler.INSTANCE;
-
In the implementation class of the
GatewayApplication
, override the initializeGatewayMeterRegistry method to supply the Micrometer’sMeterRegistry
instance. With this library, it can simply be initialized as follows and returned.@Override public GatewayMeterRegistry initializeGatewayMeterRegistry( Map<String, Object> globalApplicationConfiguration) { this.meterRegistry = metricsHandler .initializeMeterRegistry( globalApplicationConfiguration); return () -> meterRegistry; }
The framework supplies the configuration defined in the application block in the global section into the 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 for Prometheus and JMX metrics exposure can then be passed to the initializeMeterRegistry method of
MetricsHandler
, or a custom map can be created and supplied.In this method, the
PrometheusMeterRegistry
andJmxMeterRegistry
(if not disabled in the configuration) will be instantiated, and aCompositeMeterRegistry
containing both is returned. -
To start the HTTP server to expose the Prometheus metrics, after implementing the initializeGatewayMeterRegistry method as above, the Prometheus server should be started as follows:
@Override public CompletableFuture<?> start() { try { metricsHandler.initializePrometheusServer(scheduledExecutorService); } catch (IOException ex) { throw new ApplicationInitializationException( "Failed to initialize prometheus server", ex); } return CompletableFuture.completedFuture(null); }
This will start an HTTP server in the specified port to expose the Prometheus metrics in the specified path.
-
The HTTP server can be closed on shutdown as follows:
@Override public CompletableFuture<?> stop() { metricsHandler.cleanup(); return CompletableFuture.completedFuture(null); }
-
Any application-related metrics can then be exposed using the instance of
MeterRegistry
initialized in theMetricsHandle.initializeMeterRegistry
method, as described here.