Custom Metrics with Micrometer and Spring Boot

1. The Observability Toolkit: Actuator and Micrometer

To instrument our Spring Boot application, we'll use two key components that work together: Spring Boot Actuator and Micrometer.

• Spring Boot Actuator: This is a Spring Boot sub-project that adds production-ready features to your application. It exposes a set of HTTP endpoints (e.g., /health, /info, /metrics) that provide insight into the application's runtime state.

• Micrometer: This is a powerful instrumentation library that acts as a metrics facade, much like SLF4J is a facade for logging. It provides a simple, vendor-neutral API for collecting metrics in your code. Spring Boot Actuator uses Micrometer under the hood to gather and expose metrics.

The following diagram illustrates this architecture. Your application code uses the Micrometer API to define and record metrics. Micrometer organizes these into a MeterRegistry, and Spring Boot Actuator then exposes them through an endpoint (like /actuator/prometheus) for a monitoring system to collect.

To start, let's explore what Actuator provides out of the box and how to configure it.

2. Setting Up Your Project for Metrics

Let's get your hands dirty. The first step is to add the necessary dependencies and configure your application to expose metrics in a format that a monitoring system like Prometheus can understand.

Add Dependencies to build.gradle

You need two dependencies:

1. spring-boot-starter-actuator: Includes all the core Actuator functionality.
2. micrometer-registry-prometheus: Tells Micrometer to format metrics for Prometheus.

Add the following to the dependencies block in your build.gradle file:

dependencies {
    // ... your existing dependencies

    // For Observability: Actuator and Micrometer/Prometheus
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'io.micrometer:micrometer-registry-prometheus'
}

After adding these, make sure to reload your Gradle project in your IDE.

Configure application.yml

Next, you need to tell Actuator to expose the prometheus endpoint. By default, for security reasons, most endpoints are not exposed over HTTP.

Add the following configuration to your src/main/resources/application.yml file:

management:
  endpoints:
    web:
      exposure:
        include: "prometheus,health,info"
  metrics:
    export:
      prometheus:
        enabled: true
    tags: # These tags are applied to all metrics
      application: ${spring.application.name}

This configuration does two things:

• It exposes the /actuator/prometheus, /actuator/health, and /actuator/info endpoints.
• It adds a common application tag to every metric reported by your service, which is a best practice for organizing metrics.

3. Understanding Micrometer's Meter Types

Before we write code, it's essential to understand the "instruments" Micrometer provides. There are four core types of meters.

As you just saw, the primary meter types are:

For our immediate goal of tracking allowed and denied requests, the Counter is the perfect tool.

4. Instrumenting the Rate Limiter

Now, let's apply this knowledge to instrument your RateLimiterInterceptor. Our goal is to count every request that passes through the interceptor and label it as either allowed or denied.

The central component for creating meters in Micrometer is the MeterRegistry. Spring Boot automatically configures one for you, so you can simply inject it into your interceptor.

1. Inject MeterRegistry into RateLimiterInterceptor

   Modify your RateLimiterInterceptor to accept MeterRegistry in its constructor.

   import io.micrometer.core.instrument.MeterRegistry; // Add this import
   import org.springframework.stereotype.Component;
   
   @Component
   public class RateLimiterInterceptor implements HandlerInterceptor {
   
       // ... other fields like rateLimiterFactory, keyResolver, etc.
   
       private final MeterRegistry meterRegistry;
   
       public RateLimiterInterceptor(RateLimiterFactory rateLimiterFactory,
                                     RateLimitKeyResolver keyResolver,
                                     MeterRegistry meterRegistry) { // Add meterRegistry
           this.rateLimiterFactory = rateLimiterFactory;
           this.keyResolver = keyResolver;
           this.meterRegistry = meterRegistry; // Store it
       }
   
       // ...
   }
   

2. Increment a Tagged Counter

   Now, in the preHandle method, after your rate limiting logic has made a decision, you'll use the meterRegistry to increment a counter. We will use a single counter named ratelimiter.decisions.total and use a tag to create two distinct time series: one for allowed requests and one for denied requests.

   This is the most powerful feature of modern metrics systems. Instead of creating two separate metrics (allowed_requests and denied_requests), we use one metric with a decision dimension.

   Update your preHandle method:

   @Override
   public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
       // ... your existing logic to resolve key and get the rule ...
       String key = keyResolver.resolve(request);
       // Assume you have a way to get the rule, for now, we'll focus on the decision
       RateLimiter rateLimiter = rateLimiterFactory.getRateLimiter(/* rule parameters */);
   
       boolean isAllowed = rateLimiter.isAllowed(key);
   
       // --- METRICS INSTRUMENTATION ---
       String decision = isAllowed ? "allowed" : "denied";
       meterRegistry.counter("ratelimiter.decisions.total", "decision", decision).increment();
       // -------------------------------
   
       if (isAllowed) {
           return true;
       } else {
           response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
           return false;
       }
   }
   

   The line meterRegistry.counter("ratelimiter.decisions.total", "decision", decision).increment(); is the idiomatic way to handle this in Micrometer. It efficiently finds or creates a Counter with the specified name and tags and increments it.

For a deeper dive into practical Micrometer examples, the following resource is very helpful.

5. Verifying Your New Metrics

With the code in place, let's verify that it's working.

1. Run your Spring Boot application.
2. Send some requests to your rate-limited endpoint. Make sure you send enough to trigger both allowed and denied responses. For example, if your limit is 10 requests per minute, send 15 requests quickly.
3. Open your browser and navigate to http://localhost:8080/actuator/prometheus.

You will see a large text output containing all the metrics your application is exporting. Scroll through or use your browser's find function (Ctrl/Cmd + F) to search for ratelimiter_decisions_total. You should see something like this:

# HELP ratelimiter_decisions_total_total  
# TYPE ratelimiter_decisions_total_total counter
ratelimiter_decisions_total_total{application="rate-limiter",decision="allowed",} 10.0
ratelimiter_decisions_total_total{application="rate-limiter",decision="denied",} 5.0

(Note: Prometheus clients often append _total to counter names.)

Seeing these lines confirms that your custom metric is successfully being collected and exposed. You are now capturing the fundamental behavior of your rate limiter!

Conclusion

In this lesson, you've successfully laid the foundation for an observable rate limiter. You integrated Spring Boot Actuator and Micrometer, configured your application to expose metrics for Prometheus, and instrumented your core logic to produce valuable, custom metrics.

Key Takeaways:

• Observability is critical for operating services in production.
• Spring Boot Actuator exposes operational endpoints, while Micrometer provides the API to create the metrics.
• Counters are the ideal meter type for tracking events that only accumulate, like request counts.
• Tags (or labels/dimensions) are the key to creating rich, filterable metrics, allowing you to slice and dice your data (e.g., by decision).
• You can verify your custom metrics by inspecting the /actuator/prometheus endpoint.

Next Steps

You've successfully created a custom metric. The next step is to make it even more powerful. Currently, you can see the total number of allowed and denied requests. But what if you have multiple rate-limiting rules? How would you know which rule is responsible for the denials?

In the next lesson, you will instrument the rate limiter to track request counts and allowed/denied decisions per rule. This will involve adding more tags to your counter, giving you the granular insight needed to manage a multi-tenant, production-grade rate-limiting service.