Leveraging Spring Boot Actuator for Production-Grade Monitoring and Custom Metrics

Introduction

In modern application development, maintaining reliability and observability is more critical than ever. Spring Boot Actuator offers a powerful and flexible way to implement production-grade monitoring with minimal effort. It exposes a wide variety of endpoints that provide deep insights into your application’s health, metrics, and environment.

Production-grade monitoring goes beyond basic logging and error tracking; it entails continuous health checks, performance metrics, and real-time alerting to catch issues before they affect end-users. Custom metrics allow you to tailor monitoring to your application's unique behavior, enabling smarter diagnostics and decisions.

This article explores how to effectively leverage Spring Boot Actuator to build a robust monitoring setup, including how to create, expose, and secure custom metrics suited for real-world production environments.

---

Understanding Spring Boot Actuator Features

Spring Boot Actuator is a subproject of Spring Boot that adds production-ready features to help you monitor and manage your application. Here's a closer look at some of its core features:

Built-in Health Checks and Metrics

Actuator supplies many out-of-the-box health indicators, including database connectivity, disk space, and memory usage. Metrics cover JVM performance, HTTP request counts, garbage collection, and more.

This rich set of metrics allows you to spot bottlenecks and system degradation early.

Endpoint Exposure and Security Considerations

Actuator exposes various REST endpoints (e.g., /actuator/health, /actuator/metrics, /actuator/env) that provide information about your running application.

However, exposing sensitive operational data demands strong security controls. You can customize endpoint exposure to restrict or enable access based on roles, IPs, or network environments to prevent abuse.

Integration with Monitoring Tools (Prometheus, Grafana, etc.)

Actuator seamlessly integrates with popular monitoring stacks. Using Micrometer as its metrics facade, it supports exporters for Prometheus, which you can pair with Grafana to visualize data in real-time dashboards and set up alerts.

This flexibility ensures your monitoring ecosystem can be tailored to your existing infrastructure.

---

Setting Up Spring Boot Actuator for Production

To leverage Spring Boot Actuator effectively, you need to properly set it up within your application environment with production best practices.

Adding Dependencies and Basic Configuration

Add the actuator dependency in your Maven or Gradle build file:

<!-- Maven -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

// Gradle
implementation 'org.springframework.boot:spring-boot-starter-actuator'

Enable endpoints in application.properties or application.yml as needed:

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  metrics:
    export:
      prometheus:
        enabled: true

Customizing Actuator Endpoints

You might want to customize endpoint paths, enable or disable certain endpoints, or dynamically configure which endpoints are exposed:

management:
  endpoints:
    web:
      base-path: /manage
      exposure:
        include: health,metrics,my-custom
        exclude: env,heapdump

Securing Actuator Endpoints for Production Use

Securing actuator endpoints is critical in production. Spring Security can be configured to restrict access by role or authentication.

A basic security config example:

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
          .authorizeRequests()
            .antMatchers("/manage/health", "/manage/info").permitAll()
            .antMatchers("/manage/**").hasRole("ADMIN")
            .and()
          .httpBasic();
    }
}

This setup permits anonymous access to health and info endpoints but requires authentication for other actuator endpoints.

---

Implementing Custom Metrics in Spring Boot Actuator

Beyond built-in metrics, adding custom metrics tailored to your application is essential for gaining actionable insights.

Introduction to Micrometer and Metric Types

Spring Boot Actuator uses Micrometer as its metrics collection facade. Micrometer supports various metric types:

• Counters: Monotonically increasing values (e.g., number of requests)
• Gauges: Snapshot values, can go up or down (e.g., current queue size)
• Timers: Track durations and counts of events (e.g., request latency)
• Distribution Summaries: Track statistics on a stream of values

Creating Custom Counters, Gauges, and Timers

You can create these metrics by injecting the MeterRegistry bean and registering your metrics.

For example, a custom counter increasing on specific events:

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.stereotype.Component;

@Component
public class CustomMetricService {
    private final Counter customCounter;

    public CustomMetricService(MeterRegistry meterRegistry) {
        this.customCounter = Counter.builder("custom.requests.count")
            .description("Number of custom requests")
            .register(meterRegistry);
    }

    public void incrementCounter() {
        customCounter.increment();
    }
}

Similarly, you can create gauges or timers based on application logic.

Best Practices for Naming and Categorizing Metrics

Use clear, concise, and consistent names:

• Use dot notation to reflect hierarchy (e.g., service.orders.processed)
• Include units in metric names when relevant (e.g., latency_seconds)
• Attach relevant tags to differentiate sources or status (e.g., status=success)

Following these conventions enhances metrics readability and integration with dashboards and alerts.

---

Practical Implementation: Step-by-Step Guide

Configuring Metrics Registry

In a Spring Boot application, Micrometer is auto-configured when you add the actuator dependency. For exporting to Prometheus, ensure the Prometheus registry dependency is added:

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

Spring Boot will automatically pick it up and expose metrics at the /actuator/prometheus endpoint.

Writing Sample Custom Metric Code

Here is a more complete example showing a REST controller that increments a custom counter each time a particular endpoint is called:

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class CustomMetricController {

    private final Counter requestCounter;

    public CustomMetricController(MeterRegistry registry) {
        this.requestCounter = Counter.builder("custom.endpoint.requests")
            .description("Count of custom endpoint requests")
            .register(registry);
    }

    @GetMapping("/custom-endpoint")
    public String handleRequest() {
        requestCounter.increment();
        return "Custom endpoint called";
    }
}

Testing and Verifying Metrics Exposure

Run your application and hit the /custom-endpoint multiple times. Then visit:

http://localhost:8080/actuator/prometheus

Look for the custom_endpoint_requests_total metric to verify it increments as expected.

You can also query metrics programmatically via /actuator/metrics/custom.endpoint.requests.

---

Monitoring and Visualizing Metrics in Production

Configuring Prometheus Scraping

Configure your Prometheus server with a scrape job targeting your Spring Boot application's /actuator/prometheus endpoint:

scrape_configs:
  - job_name: 'spring-boot-app'
    metrics_path: '/manage/actuator/prometheus'
    static_configs:
      - targets: ['your-application-host:8080']

Adjust metrics_path and targets based on your actuator path and hostname.

Setting Up Grafana Dashboards

Connect Grafana to Prometheus as a data source. Import or create dashboards focused on JVM metrics, HTTP requests, and your custom metrics.

Grafana supports flexible queries and visualization types such as gauges, graphs, heatmaps, and alert panels, providing actionable insights.

Alerting Based on Custom Metrics

Define Prometheus alerting rules on your custom metrics to trigger alerts when thresholds are crossed (e.g., error ratio too high, request latency increases).

Configure Alertmanager for notification channels like email, Slack, or PagerDuty.

Example alert rule:

- alert: HighCustomRequestCount
  expr: rate(custom_endpoint_requests_total[5m]) > 100
  for: 2m
  labels:
    severity: warning
  annotations:
    summary: "High number of custom endpoint requests"
    description: "More than 100 requests per minute to the custom endpoint over the last 5 minutes."

---

Conclusion

Spring Boot Actuator is an indispensable tool for achieving production-grade monitoring and observability in your Spring applications. It offers rich built-in health checks and metrics, seamless integration with industry-standard monitoring tools, and an extensible model for custom metrics.

By carefully configuring actuator endpoints and securing them, you can safely expose vital operational data. Implementing custom counters, gauges, and timers using Micrometer enables granular insights tailored to your domain.

Tying metrics exposure to Prometheus and visualizing with Grafana provides a complete monitoring stack capable of proactive alerting and deep diagnostics.

Investing in a robust monitoring platform with Spring Boot Actuator pays dividends in operational reliability and faster issue resolution.

Further Reading and Resources

• Spring Boot Actuator Reference Documentation
• Micrometer Metrics Library
• Prometheus Monitoring
• Grafana Official Site

---

FAQ

Q: Is Spring Boot Actuator suitable for high-scale production environments? A: Yes. It is designed to be lightweight and performant. With correct configuration and security, actuator endpoints are production-ready and scale well.

Q: Can I customize actuator endpoints beyond what Spring Boot offers? A: Yes. You can create custom endpoints by implementing Spring Boot Actuator's Endpoint interface, allowing full flexibility.

Q: How do I secure actuator endpoints in cloud deployments? A: Use Spring Security along with cloud-native identity and access controls such as OAuth2, network policies, or API gateways.

Q: What is the best practice to name custom metrics to avoid conflicts? A: Use a domain-specific prefix and follow a consistent naming convention (e.g., appname.feature.metric) to avoid collisions and improve clarity.

Q: How can I test actuator metrics locally? A: Use embedded servers and call the actuator endpoints directly via browser or tools like curl and Postman. You can also use unit and integration testing frameworks to verify metric creation.

Related reading

• Implementing Custom Spring Boot Metrics with Micrometer and Prometheus for Real-Time Production Monitoring
• Implementing Custom Health Checks in Spring Boot Actuator for Complex Application Monitoring
• Implementing Distributed Tracing in Spring Boot with Sleuth and Zipkin for Production Monitoring