Skip to main content

This project is an implementation of the Vert.x Metrics Service Provider Interface (SPI).

It uses Micrometer for managing metrics and reporting to several backends.

Features

InfluxDB

Getting started

The modules vertx-micrometer-metrics and micrometer-registry-influx must be present in the classpath.

Maven users should add this to their project POM file:

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-micrometer-metrics</artifactId>
  <version>3.5.4</version>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-influx</artifactId>
  <version>1.0.0</version>
</dependency>

And Gradle users, to their build file:

compile 'io.vertx:vertx-micrometer-metrics:3.5.4'
compile 'io.micrometer:micrometer-registry-influx:1.0.0'

Configuration examples

Vert.x does not enable SPI implementations by default. You must enable metric collection in the Vert.x options.

var Vertx = require("vertx-js/vertx");
var vertx = Vertx.vertx({
  "metricsOptions" : {
    "influxDbOptions" : {
      "enabled" : true
    },
    "enabled" : true
  }
});

Using a specific URI and database name

var Vertx = require("vertx-js/vertx");
var vertx = Vertx.vertx({
  "metricsOptions" : {
    "influxDbOptions" : {
      "enabled" : true,
      "uri" : "http://influxdb.example.com:8888",
      "db" : "sales-department"
    },
    "enabled" : true
  }
});

With authentication

var Vertx = require("vertx-js/vertx");
var vertx = Vertx.vertx({
  "metricsOptions" : {
    "influxDbOptions" : {
      "enabled" : true,
      "userName" : "username",
      "password" : "password"
    },
    "enabled" : true
  }
});

Prometheus

Getting started

The modules vertx-micrometer-metrics and micrometer-registry-prometheus must be present in the classpath. You may also probably need vertx-web, to expose the metrics.

Maven users should add this to their project POM file:

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-micrometer-metrics</artifactId>
  <version>3.5.4</version>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
  <version>1.0.0</version>
</dependency>
<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-web</artifactId>
  <version>3.5.4</version>
</dependency>

And Gradle users, to their build file:

compile 'io.vertx:vertx-micrometer-metrics:3.5.4'
compile 'io.micrometer:micrometer-registry-prometheus:1.0.0'
compile 'io.vertx:vertx-web:3.5.4'

Configuration examples

Vert.x does not enable SPI implementations by default. You must enable metric collection in the Vert.x options

var Vertx = require("vertx-js/vertx");
var vertx = Vertx.vertx({
  "metricsOptions" : {
    "prometheusOptions" : {
      "enabled" : true
    },
    "enabled" : true
  }
});

Using an embedded HTTP server wih custom endpoint

var Vertx = require("vertx-js/vertx");
var vertx = Vertx.vertx({
  "metricsOptions" : {
    "prometheusOptions" : {
      "enabled" : true,
      "startEmbeddedServer" : true,
      "embeddedServerOptions" : {
        "port" : 8080
      },
      "embeddedServerEndpoint" : "/metrics/vertx"
    },
    "enabled" : true
  }
});

If the embedded server endpoint is not specified, it defaults to /metrics.

Binding metrics to an existing Vert.x router

var Vertx = require("vertx-js/vertx");
var Router = require("vertx-web-js/router");
var vertx = Vertx.vertx({
  "metricsOptions" : {
    "prometheusOptions" : {
      "enabled" : true
    },
    "enabled" : true
  }
});

// Later on, creating a router
var router = Router.router(vertx);
router.route("/metrics").handler(function (routingContext) {
  var prometheusRegistry = Java.type("io.vertx.micrometer.backends.BackendRegistries").getDefaultNow();
  if ((prometheusRegistry !== null && prometheusRegistry !== undefined)) {
    var response = prometheusRegistry.scrape();
    routingContext.response().end(response);
  } else {
    routingContext.fail(500);
  }
});
vertx.createHttpServer().requestHandler(router.accept).listen(8080);

JMX

Getting started

The modules vertx-micrometer-metrics and micrometer-registry-jmx must be present in the classpath.

Maven users should add this to their project POM file:

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-micrometer-metrics</artifactId>
  <version>3.5.4</version>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-jmx</artifactId>
  <version>1.0.0</version>
</dependency>

And Gradle users, to their build file:

compile 'io.vertx:vertx-micrometer-metrics:3.5.4'
compile 'io.micrometer:micrometer-registry-jmx:1.0.0'

Configuration examples

Vert.x does not enable SPI implementations by default. You must enable metric collection in the Vert.x options

var Vertx = require("vertx-js/vertx");
var vertx = Vertx.vertx({
  "metricsOptions" : {
    "jmxMetricsOptions" : {
      "enabled" : true
    },
    "enabled" : true
  }
});

With step and domain

In Micrometer, step refers to the reporting period, in seconds. domain is the JMX domain under which MBeans are registered.

var Vertx = require("vertx-js/vertx");
var vertx = Vertx.vertx({
  "metricsOptions" : {
    "jmxMetricsOptions" : {
      "enabled" : true,
      "step" : 5,
      "domain" : "my.metrics.domain"
    },
    "enabled" : true
  }
});

Advanced usage

Please refer to io.vertx.micrometer.MicrometerMetricsOptions for an exhaustive list of options.

Disable some metric domains

Restricting the Vert.x modules being monitored can be done using io.vertx.micrometer.MicrometerMetricsOptions#disabledMetricsCategories.

For a full list of domains, see io.vertx.micrometer.MetricsDomain

User-defined metrics

The Micrometer registries are accessible, in order to create new metrics or fetch the existing ones. By default, an unique registry is used and will be shared across the Vert.x instances of the JVM:

var registry = Java.type("io.vertx.micrometer.backends.BackendRegistries").getDefaultNow();

It is also possible to have separate registries per Vertx instance, by giving a registry name in metrics options. Then it can be retrieved specifically:

var Vertx = require("vertx-js/vertx");
var vertx = Vertx.vertx({
  "metricsOptions" : {
    "influxDbOptions" : {
      "enabled" : true
    },
    "registryName" : "my registry",
    "enabled" : true
  }
});

// Later on:
var registry = Java.type("io.vertx.micrometer.backends.BackendRegistries").getNow("my registry");

As an example, here is a custom timer that will track the execution time of a piece of code that is regularly called:

var registry = Java.type("io.vertx.micrometer.backends.BackendRegistries").getDefaultNow();
var timer = Java.type("io.micrometer.core.instrument.Timer").builder("my.timer").description("a description of what this timer does").register(registry);

vertx.setPeriodic(1000, function (l) {
  timer.record(function () {
    // Running here some operation to monitor
  });
});

For more examples, documentation about the Micrometer registry and how to create metrics, check Micrometer doc.

Other instrumentation

Since plain access to Micrometer registries is provided, it is possible to leverage the Micrometer API. For instance, to instrument the JVM:

var registry = Java.type("io.vertx.micrometer.backends.BackendRegistries").getDefaultNow();

new (Java.type("io.micrometer.core.instrument.binder.jvm.ClassLoaderMetrics"))().bindTo(registry);
new (Java.type("io.micrometer.core.instrument.binder.jvm.JvmMemoryMetrics"))().bindTo(registry);
new (Java.type("io.micrometer.core.instrument.binder.jvm.JvmGcMetrics"))().bindTo(registry);
new (Java.type("io.micrometer.core.instrument.binder.system.ProcessorMetrics"))().bindTo(registry);
new (Java.type("io.micrometer.core.instrument.binder.jvm.JvmThreadMetrics"))().bindTo(registry);

Label matchers

The labels (aka tags, or fields…​) can be configured through the use of matchers. Here is an example to whitelist HTTP server metrics per host name and port:

var Vertx = require("vertx-js/vertx");
var vertx = Vertx.vertx({
  "metricsOptions" : {
    "prometheusOptions" : {
      "enabled" : true
    },
    "labelMatchs" : [
      {
        "domain" : "HTTP_SERVER",
        "label" : "local",
        "value" : "localhost:8080"
      }
    ],
    "enabled" : true
  }
});

Matching rules can work on exact strings or regular expressions (the former is more performant). When a pattern matches, the value can also be renamed with an alias. By playing with regex and aliases it is possible to ignore a label partitioning:

var Vertx = require("vertx-js/vertx");
var vertx = Vertx.vertx({
  "metricsOptions" : {
    "prometheusOptions" : {
      "enabled" : true
    },
    "labelMatchs" : [
      {
        "label" : "remote",
        "type" : "REGEX",
        "value" : ".*",
        "alias" : "_"
      }
    ],
    "enabled" : true
  }
});

Here, any value for the label "remote" will be replaced with "_".

Sometimes, having some labels results in a high cardinality of label values, which can cause troubles / bad performances on the metrics backend. This is often the case with the remote label on server metrics. For that reason, there are rules in the default metrics options to ignore it (one for HTTP server, one for Net server metrics). It is still possible to stop ignoring it by clearing the label matchers:

var Vertx = require("vertx-js/vertx");
var vertx = Vertx.vertx({
  "metricsOptions" : {
    "prometheusOptions" : {
      "enabled" : true
    },
    "labelMatchs" : [],
    "enabled" : true
  }
});

Label matching uses Micrometer’s MeterFilter under the hood. This API can be accessed directly as well:

var registry = Java.type("io.vertx.micrometer.backends.BackendRegistries").getDefaultNow();

registry.config().meterFilter(Java.type("io.micrometer.core.instrument.config.MeterFilter").ignoreTags("address", "remote")).meterFilter(Java.type("io.micrometer.core.instrument.config.MeterFilter").renameTag("vertx.verticle", "deployed", "instances"));

See also other examples.

Snapshots

A io.vertx.micrometer.MetricsService can be created out of a Measured object in order to take a snapshot of its related metrics and measurements. The snapshot is returned as a JsonObject.

A well known Measured object is simply Vertx:

var MetricsService = require("vertx-micrometer-metrics-js/metrics_service");
var metricsService = MetricsService.create(vertx);
var metrics = metricsService.getMetricsSnapshot();
console.log(metrics);

Other components, such as an EventBus or a HttpServer are measurable:

var MetricsService = require("vertx-micrometer-metrics-js/metrics_service");
var server = vertx.createHttpServer();
var metricsService = MetricsService.create(server);
var metrics = metricsService.getMetricsSnapshot();
console.log(metrics);

Finally it is possible to filter the returned metrics from their base names:

var MetricsService = require("vertx-micrometer-metrics-js/metrics_service");
var metricsService = MetricsService.create(vertx);
// Client + server
var metrics = metricsService.getMetricsSnapshot("vertx.http");
console.log(metrics);

Vert.x core tools metrics

This section lists all the metrics generated by monitoring the Vert.x core tools.

Net Client

Metric type Metric name Description

Gauge

vertx_net_client_connections{local=<local address>,remote=<remote address>}

Number of connections to the remote host currently opened.

Summary

vertx_net_client_bytesReceived{local=<local address>,remote=<remote address>}

Number of bytes received from the remote host.

Summary

vertx_net_client_bytesSent{local=<local address>,remote=<remote address>}

Number of bytes sent to the remote host.

Counter

vertx_net_client_errors{local=<local address>,remote=<remote address>,class=<class>}

Number of errors.

HTTP Client

Metric type Metric name Description

Gauge

vertx_http_client_connections{local=<local address>,remote=<remote address>}

Number of connections to the remote host currently opened.

Summary

vertx_http_client_bytesReceived{local=<local address>,remote=<remote address>}

Number of bytes received from the remote host.

Summary

vertx_http_client_bytesSent{local=<local address>,remote=<remote address>}

Number of bytes sent to the remote host.

Counter

vertx_http_client_errors{local=<local address>,remote=<remote address>,class=<class>}

Number of errors.

Gauge

vertx_http_client_requests{local=<local address>,remote=<remote address>}

Number of requests waiting for a response.

Counter

vertx_http_client_requestCount{local=<local address>,remote=<remote address>,method=<http method>}

Number of requests sent.

Timer

vertx_http_client_responseTime{local=<local address>,remote=<remote address>}

Response time.

Counter

vertx_http_client_responseCount{local=<local address>,remote=<remote address>,code=<response code>}

Number of received responses.

Gauge

vertx_http_client_wsConnections{local=<local address>,remote=<remote address>}

Number of websockets currently opened.

Datagram socket

Metric type Metric name Description

Summary

vertx_datagram_bytesReceived{local=<local>,remote=<remote>}

Total number of bytes received on the <host>:<port> listening address.

Summary

vertx_datagram_bytesSent{remote=<remote>}

Total number of bytes sent to the remote host.

Counter

vertx_datagram_errors{class=<class>}

Total number of errors.

Net Server

Metric type Metric name Description

Gauge

vertx_net_server_connections{local=<local address>}

Number of opened connections to the Net Server.

Summary

vertx_net_server_bytesReceived{local=<local address>}

Number of bytes received by the Net Server.

Summary

vertx_net_server_bytesSent{local=<local address>}

Number of bytes sent by the Net Server.

Counter

vertx_net_server_errors{local=<local address>,class=<class>}

Number of errors.

HTTP Server

Metric type Metric name Description

Gauge

vertx_http_server_connections{local=<local address>}

Number of opened connections to the HTTP Server.

Summary

vertx_http_server_bytesReceived{local=<local address>}

Number of bytes received by the HTTP Server.

Summary

vertx_http_server_bytesSent{local=<local address>}

Number of bytes sent by the HTTP Server.

Counter

vertx_http_server_errors{local=<local address>,class=<class>}

Number of errors.

Gauge

vertx_http_server_requests{local=<local address>}

Number of requests being processed.

Counter

vertx_http_server_requestCount{local=<local address>,method=<http method>,code=<response code>}

Number of processed requests.

Counter

vertx_http_server_requestResetCount{local=<local address>}

Number of requests reset.

Timer

vertx_http_server_processingTime{local=<local address>}

Request processing time.

Gauge

vertx_http_client_wsConnections{local=<local address>}

Number of websockets currently opened.

Event Bus

Metric type Metric name Description

Gauge

vertx_eventbus_handlers{address=<address>}

Number of event bus handlers in use.

Counter

vertx_eventbus_errors{address=<address>,class=<class>}

Number of errors.

Summary

vertx_eventbus_bytesWritten{address=<address>}

Total number of bytes sent while sending messages to event bus cluster peers.

Summary

vertx_eventbus_bytesRead{address=<address>}

Total number of bytes received while reading messages from event bus cluster peers.

Gauge

vertx_eventbus_pending{address=<address>,side=<local/remote>}

Number of messages not processed yet. One message published will count for N pending if N handlers are registered to the corresponding address.

Counter

vertx_eventbus_published{address=<address>,side=<local/remote>}

Number of messages published (publish / subscribe).

Counter

vertx_eventbus_sent{address=<address>,side=<local/remote>}

Number of messages sent (point-to-point).

Counter

vertx_eventbus_received{address=<address>,side=<local/remote>}

Number of messages received.

Counter

vertx_eventbus_delivered{address=<address>,side=<local/remote>}

Number of messages delivered to handlers.

Counter

vertx_eventbus_replyFailures{address=<address>,failure=<failure name>}

Number of message reply failures.

Timer

vertx_eventbus_processingTime{address=<address>}

Processing time for handlers listening to the address.

Vert.x pool metrics

This section lists all the metrics generated by monitoring Vert.x pools.

There are two types currently supported:

  • worker (see WorkerExecutor)

  • datasource (created with Vert.x JDBC client)

Note
Vert.x creates two worker pools upfront, worker-thread and internal-blocking.
Metric type Metric name Description

Timer

vertx_pool_queue_delay{pool_type=<type>,pool_name=<name>}

Time waiting for a resource (queue time).

Gauge

vertx_pool_queue_size{pool_type=<type>,pool_name=<name>}

Number of elements waiting for a resource.

Timer

vertx_pool_usage{pool_type=<type>,pool_name=<name>}

Time using a resource (i.e. processing time for worker pools).

Gauge

vertx_pool_inUse{pool_type=<type>,pool_name=<name>}

Number of resources used.

Counter

vertx_pool_completed{pool_type=<type>,pool_name=<name>}

Number of elements done with the resource (i.e. total number of tasks executed for worker pools).

Gauge

vertx_pool_ratio{pool_type=<type>,pool_name=<name>}

Pool usage ratio, only present if maximum pool size could be determined.

Verticle metrics

Metric type Metric name Description

Gauge

vertx_verticle_deployed{name=<name>}

Number of verticle instances deployed.