Monitoring
API docs
You are currently viewing the documentation for the unreleased version 5.0.0.CR2 of Vert.x. Visit the latest stable version of this page.

Vert.x Health Checks

This component provides a simple way to compute health checks. Health checks are used to express the current state of the application in very simple terms: UP or DOWN.

Using Vert.x Health Checks

Add the following dependency:

  • Maven (in your pom.xml):

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-health-check</artifactId>
  <version>5.0.0.CR2</version>
</dependency>

  • Gradle (in your build.gradle file):

compile 'io.vertx:vertx-health-check:5.0.0.CR2'

Creating the health check object.

The central object is HealthChecks. You can create a new instance using:

HealthChecks hc = HealthChecks.create(vertx);

hc.register(
  "my-procedure",
  promise -> promise.complete(Status.OK()));

// Register with a timeout. The check fails if it does not complete in time.
// The timeout is given in ms.
hc.register(
  "my-procedure",
  2000,
  promise -> promise.complete(Status.OK()));

Once you have created this object you can register and unregister procedures.

Procedures

A procedure is a function checking some aspect of the system to deduce the current health. It reports a Status indicating whether the test has passed or failed. This function must not block and report to the given Promise whether it succeeded or failed.

When you register a procedure, you give a name and the function (handler) executing the check.

Rules deducing the status are the following:

  • if the promise is marked as failed, the check is considered as KO

  • if the promise is completed successfully but without a Status, the check is considered as OK.

  • if the promise is completed successfully with a Status marked as OK, the check is considered as OK.

  • if the promise is completed successfully with a Status marked as KO, the check is considered as KO.

Status can also provide additional data:

healthChecks.register("my-procedure-name", promise -> {
  // Status can provide additional data provided as JSON
  promise.complete(Status.OK(new JsonObject().put("available-memory", "2mb")));
});

healthChecks.register("my-second-procedure-name", promise -> {
  promise.complete(Status.KO(new JsonObject().put("load", 99)));
});

Procedures can be organised in groups. The procedure name indicates the group (separated by /). The procedures are organised as a tree.

healthChecks.register("a-group/my-procedure-name", promise -> {
  //....
});
// Groups can contain other groups
healthChecks.register("a-group/a-second-group/my-second-procedure-name", promise -> {
  //....
});

Examples of procedures

This section provides example of common health checks.

SQL client

This check reports whether a connection to the database can be established:

healthChecks.register("database", promise ->
  pool.getConnection()
    .compose(SqlConnection::close)
    .<Status>mapEmpty()
    .onComplete(promise)
);

Event bus

This check reports whether a consumer is ready on the event bus. The protocol, in this example, is a simple ping/pong, but it can be more sophisticated. This check can be used to check whether a verticle is ready if it’s listening on a specific event address.

healthChecks.register("receiver", promise ->
  vertx.eventBus().request("health", "ping")
    .onSuccess(msg -> {
      promise.complete(Status.OK());
    })
    .onFailure(err -> {
      promise.complete(Status.KO());
    })
);

Exposing health checks on the event bus

While exposing the health checks using HTTP with the Vert.x web handler is convenient, it can be useful to expose the data differently. This section gives an example to expose the data on the event bus:

vertx.eventBus().consumer("health", message ->
  healthChecks.checkStatus()
    .onSuccess(message::reply)
    .onFailure(err -> message.fail(0, err.getMessage()))
);