Expose Vert.x Metrics for Prometheus, visualize in Grafana

This document will show you how to expose Vert.x Metrics for Prometheus and visualize them in Grafana.

What you will build

You will build a web server that:

  • generates greetings upon request on the EventBus

  • replies to GET requests on the /greeting path,

  • exposes metrics for Prometheus on the /metrics path.

Then you will configure Prometheus to scrape the metrics and Grafana to visualize them.

The application fits in just a single MainVerticle class

What you need

  • A text editor or IDE

  • Java 11 or higher

  • Maven or Gradle

  • Prometheus (or Docker)

  • Grafana (or Docker)

Create a project

The code of this project contains Maven and Gradle build files that are functionally equivalent.

Using Maven

Here is the content of the pom.xml file you should be using:

Using Gradle

Assuming you use Gradle with the Kotlin DSL, here is what your build.gradle.kts file should look like:

Implementing the server

Greeting generator

First, let’s define a few greetings:

Then, we will define a consumer for the greetings address on the EventBus. This consumer picks a random greeting and returns it after an arbitrary amount of time:

HTTP server

We’ll need a Vert.x Web Router to start with:

Then let’s create a handler for GET requests on the greeting path:

The Vert.x Micrometer Metrics module provides a Vert.x Web handler that comes in handy when you need to expose data in the Prometheus text format:

With the Vert.x Web Router configured, we can start the HTTP server:

Lastly, the MainVerticle needs a main method:

Important
 The Vert.x instance must be created with metrics options enabled.

Running the application

You can run the application:

  • straight from your IDE or,

  • with Maven: mvn compile exec:java, or

  • with Gradle: ./gradlew run (Linux, macOS) or gradlew run (Windows).

The following examples use the HTTPie command line HTTP client. Please refer to the installation documentation if you don’t have it installed on your system yet.

Testing the greeting server

To get a greeting from the server, open your terminal and execute this:

http :8080/greeting

You should see something like:

HTTP/1.1 200 OK
content-length: 11
content-type: text/plain

Hola Mundo!

Testing the metrics endpoint

To get the metrics:

http :8080/metrics

You should see something like:

Scraping with Prometheus

If you’re not familiar with Prometheus, check out the getting started guide.

You need to configure the Prometheus server to scrape localhost:8080.

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

To run a pre-configured Prometheus server on your machine with Docker, clone the repository of this tutorial, open your terminal and execute this:

docker run --network host -v ${PWD}/prometheus:/etc/prometheus -it prom/prometheus

Visualizing with Grafana

If you’re not familiar with Grafana, check out the getting started guide.

To run a Grafana server on your machine with Docker, clone the repository of this tutorial, open your terminal and execute this:

docker run --network host -it grafana/grafana

As a starting point, you can import the dashboard from grafana/dashboard.json.

You should see something like:

Dashboard

Dashboard

Summary

This document covered:

  1. setting up Vert.x to expose metrics for Prometheus,

  2. visualizing metric data in Grafana.

See also

Last published: 2023-12-15 01:11:55 +0000.