Vert.x Monitoring

In modern microservice architectures, maintaining high availability and predictable performance relies heavily on deep v

In modern microservice architectures, maintaining high availability and predictable performance relies heavily on deep visibility into application health, resource utilization, and operational metrics. Eclipse Vert.x is engineered for high-throughput, non-blocking, and reactive workloads. However, these very architectural traits mean that traditional monitoring paradigms often fall short of capturing the true internal state of the system.

This guide explores how to establish a robust monitoring pipeline within a Vert.x application. By leveraging the Metrics SPI (Service Provider Interface), developers can seamlessly extract core performance telemetry and expose it to ecosystem standards like Prometheus and Grafana for real-time visualization.

At its core, the Vert.x metrics architecture is completely decoupled from concrete monitoring implementations through an SPI design. This means you can inject monitoring capabilities simply by adding dependencies, leaving your core business logic entirely untouched.

A comprehensive monitoring strategy for Vert.x typically targets several key dimensions:

  • HTTP/TCP Servers and Clients: Tracking request throughput, end-to-end response latency, and active concurrent connections.
  • EventBus: Measuring message production rates, processing delays, and pending handler queues.
  • Connection Pools: Monitoring resource utilization and wait-time distributions for database or client pools.
  • JVM Telemetry: Keeping an eye on heap allocations, garbage collection (GC) pauses, and active thread counts.
    The Vert.x project officially endorses Micrometer as the instrumentation facade of choice. Micrometer acts as an application-level metrics layer, allowing you to easily bridge runtime statistics to dominant observability backends like Prometheus, Datadog, or InfluxDB.

1. Adding Dependencies

To enable Micrometer metrics in your Maven-based Vert.x project, include the vertx-micrometer-metrics module alongside the required Prometheus registry binding in your pom.xml:

<dependencies>
  <!-- Vert.x Micrometer core metrics module -->
  <dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-micrometer-metrics</artifactId>
    <version>4.5.1</version>
  </dependency>

  <!-- Prometheus registry implementation -->
  <dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
    <version>1.12.2</version>
  </dependency>
</dependencies>

2. Configuring and Initializing Vert.x Metrics

When instantiating your Vertx context, configure the runtime options using VertxOptions to activate the Micrometer backend and spin up an embedded endpoint for Prometheus scraping.

import io.vertx.core.Vertx;
import io.vertx.core.VertxOptions;
import io.vertx.micrometer.MicrometerMetricsOptions;
import io.vertx.micrometer.VertxPrometheusOptions;

public class MetricsApp {
  public static void main(String[] args) {
    VertxOptions options = new VertxOptions()
      .setMetricsOptions(new MicrometerMetricsOptions()
        .setPrometheusOptions(new VertxPrometheusOptions()
          .setEnabled(true)
          .setStartEmbeddedServer(true) // Embed an HTTP server to expose metrics
          .setEmbeddedServerEndpoint("/metrics") // Scrape path for Prometheus
          .setEmbeddedServerPort(8080)) // Port for the metrics endpoint
        .setEnabled(true));

    Vertx vertx = Vertx.vertx(options);

    // Deploy your primary business verticle
    vertx.deployVerticle(new MainVerticle(), ar -> {
      if (ar.succeeded()) {
        System.out.println("Application started successfully. Metrics exposed at http://localhost:8080/metrics");
      } else {
        System.err.println("Deployment failed: " + ar.cause());
      }
    });
  }
}

With this configuration in place, Vert.x automatically collects and aggregates JVM stats, EventBus traffic, and HTTP server metrics, formatting them natively for Prometheus scrapers at http://localhost:8080/metrics.

Capturing Custom Business Metrics

While framework-level metrics provide vital infrastructure insights, production systems also demand visibility into domain-specific activities—such as order creation success rates or external payment gateway latencies. Micrometer provides a lightweight API to instrument custom code paths effortlessly.

The following example demonstrates how to register and increment a custom counter inside a Vert.x AbstractVerticle:

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import io.vertx.core.AbstractVerticle;

public class MainVerticle extends AbstractVerticle {

  private Counter orderCounter;

  @Override
  public void start() {
    // Retrieve the global MeterRegistry instance
    MeterRegistry registry = io.vertx.micrometer.backends.BackendRegistries.getDefaultNow();

    if (registry != null) {
      // Define a custom domain counter with contextual tags
      orderCounter = Counter.builder("app.orders.created")
        .description("Total number of successfully created orders")
        .tag("region", "cn-north")
        .register(registry);
    }

    // Simulate an HTTP endpoint handling web traffic
    vertx.createHttpServer().requestHandler(req -> {
      if (req.path().equals("/order") && req.method().name().equals("POST")) {
        // Execute business logic...
        
        // Increment the domain metric
        if (orderCounter != null) {
          orderCounter.increment();
        }

        req.response().end("Order created successfully!");
      } else {
        req.response().setStatusCode(404).end("Not Found");
      }
    }).listen(8888);
  }
}

Connecting Prometheus and Grafana

To achieve long-term metric persistence and rich operational dashboards, pair Prometheus with Grafana.

  1. Configure Prometheus Scraping:
    Update your prometheus.yml configuration file to pull telemetry from your Vert.x application instance:

    scrape_configs:
  - job_name: 'vertx-app'
    static_configs:
      - targets: ['localhost:8080']

  2. Provision Dashboards in Grafana:

    • Spin up Prometheus and Grafana containers or services.
    • Add your Prometheus instance as a data source inside Grafana.
    • Build customized dashboards using PromQL queries. For instance, to calculate the HTTP request rate over a minute window, use:
      rate(http_server_requests_seconds_count{}[1m])
    • Alternatively, accelerate your setup by importing community-maintained Vert.x and Micrometer dashboard templates (such as Dashboard ID 12895), giving you an out-of-the-box overview of CPU usage, memory footprints, and EventBus queue depths.

Conclusion

Observability is a non-negotiable pillar for maintaining resilient reactive architectures. By harnessing the built-in Micrometer SPI in Vert.x, developers can effortlessly stream low-level reactive runtimes, EventBus metrics, and JVM vitals into Prometheus. Combined with custom domain metrics and Grafana visualization, engineering teams gain the precise, real-time insights needed to proactively detect bottlenecks and ensure absolute system stability in production environments.