Chapter 5. Monitoring your application

Procedure

1. Include the vertx-micrometer and vertx-web dependencies in the pom.xml file of your application:

   pom.xml

   <dependency>
     <groupId>io.vertx</groupId>
     <artifactId>vertx-micrometer-metrics</artifactId>
   </dependency>
   <dependency>
     <groupId>io.vertx</groupId>
     <artifactId>vertx-web</artifactId>
   </dependency>

2. Starting with version 3.5.4, exposing metrics for Prometheus requires that you configure the Eclipse Vert.x options in a custom Launcher class.

   In your custom Launcher class, override the beforeStartingVertx and afterStartingVertx methods to configure the metrics engine, for example:

   Example CustomLauncher.java file

   package org.acme;
   
   import io.micrometer.core.instrument.Meter;
   import io.micrometer.core.instrument.config.MeterFilter;
   import io.micrometer.core.instrument.distribution.DistributionStatisticConfig;
   import io.micrometer.prometheus.PrometheusMeterRegistry;
   import io.vertx.core.Vertx;
   import io.vertx.core.VertxOptions;
   import io.vertx.core.http.HttpServerOptions;
   import io.vertx.micrometer.MicrometerMetricsOptions;
   import io.vertx.micrometer.VertxPrometheusOptions;
   import io.vertx.micrometer.backends.BackendRegistries;
   
   public class CustomLauncher extends Launcher {
   
     @Override
     public void beforeStartingVertx(VertxOptions options) {
       options.setMetricsOptions(new MicrometerMetricsOptions()
         .setPrometheusOptions(new VertxPrometheusOptions().setEnabled(true)
           .setStartEmbeddedServer(true)
           .setEmbeddedServerOptions(new HttpServerOptions().setPort(8081))
           .setEmbeddedServerEndpoint("/metrics"))
         .setEnabled(true));
     }
   
     @Override
     public void afterStartingVertx(Vertx vertx) {
       PrometheusMeterRegistry registry = (PrometheusMeterRegistry) BackendRegistries.getDefaultNow();
       registry.config().meterFilter(
         new MeterFilter() {
           @Override
           public DistributionStatisticConfig configure(Meter.Id id, DistributionStatisticConfig config) {
             return DistributionStatisticConfig.builder()
               .percentilesHistogram(true)
               .build()
               .merge(config);
           }
       });
   }

3. Create a custom Verticle class and override the start method to collect metrics. For example, measure the execution time using the Timer class:

   Example CustomVertxApp.java file

   package org.acme;
   
   import io.micrometer.core.instrument.MeterRegistry;
   import io.micrometer.core.instrument.Timer;
   import io.vertx.core.AbstractVerticle;
   import io.vertx.core.Vertx;
   import io.vertx.core.VertxOptions;
   import io.vertx.core.http.HttpServerOptions;
   import io.vertx.micrometer.backends.BackendRegistries;
   
   public class CustomVertxApp extends AbstractVerticle {
   
     @Override
     public void start() {
       MeterRegistry registry = BackendRegistries.getDefaultNow();
       Timer timer = Timer
         .builder("my.timer")
         .description("a description of what this timer does")
         .register(registry);
   
       vertx.setPeriodic(1000, l -> {
         timer.record(() -> {
   
           // Do something
   
         });
       });
     }
   }

4. Set the <vertx.verticle> and <vertx.launcher> properties in the pom.xml file of your application to point to your custom classes:

   <properties>
     ...
     <vertx.verticle>org.acme.CustomVertxApp</vertx.verticle>
     <vertx.launcher>org.acme.CustomLauncher</vertx.launcher>
     ...
   </properties>

5. Launch your application:

   $ mvn vertx:run

6. Invoke the traced endpoint several times:

   $ curl http://localhost:8080/
   Hello

7. Wait at least 15 seconds for collection to occur, and see the metrics in Prometheus UI:

   1. Open the Prometheus UI at http://localhost:9090/ and type hello into the Expression box.
   2. From the suggestions, select for example application:hello_count and click Execute.
   3. In the table that is displayed, you can see how many times the resource method was invoked.
   4. Alternatively, select application:hello_time_mean_seconds to see the mean time of all the invocations.

   Note that all metrics you created are prefixed with application:. There are other metrics, automatically exposed by Eclipse Vert.x as the Eclipse MicroProfile Metrics specification requires. Those metrics are prefixed with base: and vendor: and expose information about the JVM in which the application runs.