A Guide to Micrometer in Quarkus

1. Introduction

Monitoring and observability are indispensable aspects of modern application development, especially in cloud-native and microservices architectures.

Quarkus has emerged as a popular choice for building Java-based applications and is known for its lightweight and fast nature. Integrating Micrometer into our Quarkus applications provides a robust solution for monitoring various aspects of our application’s performance and behavior.

In this tutorial, we’ll explore advanced monitoring techniques for using Micrometer in Quarkus.

2. Maven Dependency

To use Micrometer with Quarkus, we need to include the quarkus-micrometer-registry-prometheus dependency:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-micrometer-registry-prometheus</artifactId>
    <version>3.11.0</version>
</dependency>

This dependency provides the necessary interfaces and classes for instrumenting our code and includes a specific registry implementation. Specifically, the micrometer-registry-prometheus is a popular choice that implements the Prometheus REST endpoint to expose metrics in our Quarkus application.
This also transitively includes the core quarkus-micrometer dependency. In addition to the metrics registry we’ll use for custom metrics, this provides out-of-the-box metrics from the JVM, thread pools, and HTTP requests.

3. Counters

Now that we’ve seen how to include Micrometer in our Quarkus application, let’s implement custom metrics. First, we’ll look at adding basic counters to our application to track the usage of various operations.

Our Quarkus application implements a simple endpoint to determine whether a given string is a palindrome. Palindromes are strings that read the same backward and forward, such as “radar” or “level”. We specifically want to count each time this palindrome check is invoked.

Let’s create a Micrometer counter:

@Path("/palindrome")
@Produces("text/plain")
public class PalindromeResource {

    private final MeterRegistry registry;

    public PalindromeResource(MeterRegistry registry) {
        this.registry = registry;
    }

    @GET
    @Path("check/{input}")
    public boolean checkPalindrome(String input) {
        registry.counter("palindrome.counter").increment();
        boolean result = internalCheckPalindrome(input);
        return result;
    }

    private boolean internalCheckPalindrome(String input) {
        int left = 0;
        int right = input.length() - 1;

        while (left < right) {
            if (input.charAt(left) != input.charAt(right)) {
                return false;
            }
            left++;
            right--;
        }
        return true;
    }
}

We can execute our palindrome check with a GET request to ‘/palindrome/check/{input}‘, where input is the word we want to check.

To implement our counter, we injected the MeterRegistry into our PalindromeResource. Notably, we increment() the counter before every palindrome check. Finally, after calling the endpoint several times, we can call the ‘/q/metrics‘ endpoint to see the counter metric. We’ll find the number of times we called our operation as the palindrome_counter_total entry.

4. Timers

We can also track the duration of palindrome checks. Therefore to achieve this, we’ll add a Micrometer Timer to our PalindromeResource:

@GET
@Path("check/{input}")
public boolean checkPalindrome(String input) {
    Timer.Sample sample = Timer.start(registry);
    boolean result = internalCheckPalindrome(input);
    sample.stop(registry.timer("palindrome.timer"));
    return result;
}

First, we start the timer, which creates a Timer.Sample that tracks the operation duration. We then call our internalCheckPalindrome() method after starting the timer. Finally, we stop the timer and record the elapsed time. By incorporating this timer, we can monitor the duration of each palindrome check, which also enables us to identify performance bottlenecks and optimize the efficiency of our application.

Micrometer follows Prometheus conventions for timer metrics, converting measured durations into seconds and including this unit in the metric name.

After calling the endpoint multiple times we can see the following metrics at the same metrics endpoint:

• palindrome_timer_seconds_count – how many times the counter was called
  
• palindrome_timer_seconds_sum – the total duration of all method calls
• palindrome_timer_seconds_max – the maximum observed duration within a decaying interval

Finally, looking at the data produced by the timer we can use the sum and the count to calculate how long (on average) it takes to determine if a string is palindrome.

5. Gauges

A gauge is a metric representing a single numerical value that can arbitrarily go up and down. Gauges allow us to monitor real-time metrics, providing insights into dynamic values and helping us quickly respond to changing conditions. They’re particularly useful for tracking frequently fluctuating values, such as queue sizes and thread counts.

Let’s say we want to keep all the checked words in the program memory and save them to the database or send them to another service. We’ll want to keep track of the number of elements to monitor our program’s memory. Let’s implement a gauge for this.

We’ll initialize a gauge in our constructor after injecting the registry and we’ll declare an empty list to store the inputs:

private final LinkedList<String> list = new LinkedList<>();

public PalindromeResource(MeterRegistry registry) {
    this.registry = registry;
    registry.gaugeCollectionSize("palindrome.list.size", Tags.empty(), list);
}

Now we’ll add elements to our list whenever we receive input and check the palindrome_list_size value to see the size of our gauge:

list.add(input);

The gauge effectively gives us a snapshot of the current program state.

We can also simulate the emptying of the list and reset our gauge:

@DELETE
@Path("empty-list")
public void emptyList() {
    list.clear();
}

This shows that gauges are real-time measurements. After clearing the list, our palindrome_list_size gauge is reset to zero until we check more palindromes.

6. Conclusion

In our journey with Micrometer in Quarkus, we’ve learned to track how often we perform specific operations using counters, the duration of operations with timers, and monitor real-time metrics with gauges. These tools provide valuable insights into our application’s performance, enabling us to make informed decisions for optimization.