Spring Boot Actuator Deep Dive: Custom Metrics and Health Indicators

Most Spring Boot projects have the Actuator dependency in pom.xml or build.gradle without anyone touching it. Then something breaks in production and you need visibility into the JVM. That is when you either have a useful tool or a mystery box.

Spring Boot Actuator gives you a set of HTTP endpoints (and JMX MBeans) that expose the internals of your running application. Out of the box you get /health, /info, /metrics, and with a few lines of configuration you can unlock /env, /loggers, /heapdump, and more. The key constraint is that Spring Boot deliberately exposes only /health over HTTP by default. Everything else stays hidden until you explicitly whitelist it, which is the right security posture.

The four main concepts to understand are:

• Endpoints – individual operational units identified by an id (like health, info, metrics, prometheus)
• Operations – HTTP methods on an endpoint: @ReadOperation (GET), @WriteOperation (POST), @DeleteOperation (DELETE)
• Health Indicators – components that report the health of a specific subsystem (database, queue, disk)
• Metrics – numerical measurements exported via Micrometer and surfaced through the /metrics endpoint

Actuator is also the reason Spring Boot can integrate with Kubernetes probes, Prometheus scraping, and Datadog auto-discovery without you writing a single line of configuration code. If you are building microservices, this sits naturally alongside an API gateway in your operational infrastructure.

When to Use Actuator Endpoints and When to Avoid Them

Introduction

Spring Boot Actuator exposes operational information that helps teams understand whether an application is healthy and how it is behaving in production. This deep dive covers endpoint exposure and security, custom health indicators, Micrometer metrics, Kubernetes probes, and integrations with monitoring systems such as Prometheus and Datadog.

Actuator Architecture with Micrometer

Here is how the components connect. Micrometer sits in the middle as the metrics facade, bridging your application code with whatever monitoring backend you have running.

graph TD
    App["Your Spring Boot Application"]
    Actuator["Spring Boot Actuator"]
    Endpoints["Actuator Endpoints<br/>/health /metrics /info<br/>/prometheus /loggers"]
    HealthIndicators["Health Indicators<br/>DB, Redis, Disk, Custom"]
    Micrometer["Micrometer<br/>MeterRegistry"]
    Metrics["Micrometer Metrics<br/>@Timed @Gauge @Counter<br/>@Metered"]
    Backends["Monitoring Backends<br/>Prometheus Datadog<br/>Elastic InfluxDB"]

    App --> Actuator
    App --> Metrics
    Actuator --> Endpoints
    Actuator --> HealthIndicators
    Metrics --> Micrometer
    Micrometer --> Backends
    HealthIndicators --> Actuator

You instrument application code with Micrometer annotations (@Timed, @Gauge, @Counter) or by registering meters directly with a MeterRegistry bean. Actuator aggregates health status from every registered HealthIndicator and exposes it through its endpoints. The MeterRegistry collects metrics and forwards them to whichever exporter you have configured – Prometheus, Datadog, Elastic, InfluxDB, or one of the many others Micrometer supports.

Failure Scenarios

Actuator behaves well in most cases, but a few misconfigurations can turn it into a liability.

Endpoint Exposure Risks

Publishing actuator endpoints publicly without authentication is handing your operational manual to anyone who asks. An attacker hitting /env might walk away with database credentials. /heapdump can dump your entire JVM heap, creating multi-gigabyte files on disk or exposing sensitive in-memory data in the process. /threaddump reveals thread names, which occasionally encode business logic details or user identifiers you did not intend to expose.

Health Endpoint Performance Degradation

If a HealthIndicator makes network calls to a database or remote cache, /health blocks until those calls succeed or timeout. During a genuine upstream outage, a slow health check tells your load balancer the instance is unhealthy even when it would recover on its own. This cascades. Keep health checks fast, and use circuit breakers if you must check external systems at all.

Metric Cardinality Explosion

This is the mistake I see most often with teams new to Micrometer. If you register request.latency with a userId tag and your app has thousands of users, you now have thousands of distinct time series. Session IDs, request IDs, and any other high-cardinality dimension cause the same problem. Your metrics backend chokes, your application slows as the meter registry grows, and you spend an afternoon removing tags you should never have added.

Endpoint ID Collisions

Defining @Endpoint(id = “metrics”) silently conflicts with the built-in metrics endpoint. Spring Boot does not warn you. The behavior becomes unpredictable, with your custom endpoint winning some of the time and the built-in winning the rest.

Built-in vs Custom Health Indicators and Metrics

The tradeoffs here are straightforward.

For metrics, the built-in auto-configuration already gives you JVM memory, GC, thread counts, HTTP request timings, and database connection pool stats without any code. Custom metrics make sense for business-specific measurements: orders processed per minute, internal cache size, how long a multi-step workflow takes. The built-in ones cover the infrastructure layer; custom ones cover your specific domain.

Implementation Examples

Time to look at actual code. If you are following the Spring Boot learning roadmap, this is the level where you move beyond configuration and start instrumenting your own application behavior.

Custom Endpoint with @Endpoint

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.boot.actuate.endpoint.annotation.WriteOperation;
import org.springframework.stereotype.Component;

import java.time.Instant;
import java.util.HashMap;
import java.util.Map;

@Component
@Endpoint(id = "application")
public class ApplicationInfoEndpoint {

    private final Instant startTime = Instant.now();

    @ReadOperation
    public Map<String, Object> info() {
        Map<String, Object> info = new HashMap<>();
        info.put("uptimeSeconds", Instant.now().getEpochSecond() - startTime.getEpochSecond());
        info.put("timestamp", Instant.now().toString());
        return info;
    }

    @WriteOperation
    public String restart() {
        // In a real application, this would trigger a graceful restart
        return "Restart initiated";
    }
}

The @Endpoint annotation marks this class as an Actuator endpoint. Methods annotated with @ReadOperation respond to GET requests, @WriteOperation to POST, and @DeleteOperation to DELETE. The id attribute sets the URL path – so this becomes /actuator/application.

Custom Health Indicator

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class DatabaseHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        try {
            // Perform actual database connectivity check
            boolean isConnected = checkDatabaseConnection();
            if (isConnected) {
                return Health.up()
                    .withDetail("database", "PrimaryDB")
                    .withDetail("status", "Connected")
                    .build();
            }
        } catch (Exception e) {
            return Health.down()
                .withDetail("error", e.getMessage())
                .build();
        }
        return Health.unknown().build();
    }

    private boolean checkDatabaseConnection() {
        // Actual DB check implementation
        return true;
    }
}

If you want exception handling handled for you, extend AbstractHealthIndicator instead. One rule that never changes: keep health() fast. No long timeouts here, ever.

Recording Metrics with Micrometer

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

import java.util.concurrent.atomic.AtomicInteger;

@Component
public class OrderMetrics {

    private final Counter orderCounter;
    private final AtomicInteger pendingOrders;

    public OrderMetrics(MeterRegistry registry) {
        this.orderCounter = Counter.builder("orders.processed")
            .description("Total number of processed orders")
            .tag("service", "order-service")
            .register(registry);

        this.pendingOrders = new AtomicInteger(0);
        Gauge.builder("orders.pending", pendingOrders, AtomicInteger::get)
            .description("Number of pending orders")
            .register(registry);
    }

    @Timed(value = "order.processing.time", description = "Time taken to process an order")
    public void processOrder() {
        pendingOrders.incrementAndGet();
        try {
            // Order processing logic
        } finally {
            pendingOrders.decrementAndGet();
            orderCounter.increment();
        }
    }
}

@Timed records how long the method takes and exports it as a timer metric automatically. @Gauge tracks values that go up and down. @Counter increments in one direction only.

Exporting Health Status as a Metric

import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.boot.actuate.health.HealthEndpoint;
import org.springframework.boot.actuate.health.Status;
import org.springframework.context.annotation.Configuration;

@Configuration
public class HealthMetricsExport {

    public HealthMetricsExport(MeterRegistry registry, HealthEndpoint healthEndpoint) {
        Gauge.builder("health.status", healthEndpoint, ep -> getStatusCode(ep.health().getStatus()))
            .strongReference(true)
            .register(registry);
    }

    private int getStatusCode(Status status) {
        return switch (status.getCode()) {
            case "UP" -> 3;
            case "OUT_OF_SERVICE" -> 2;
            case "DOWN" -> 1;
            default -> 0;
        };
    }
}

This bridges health and metrics worlds, so you can alert on health status changes using your existing metrics tooling.

Observability Checklist

A Spring Boot app is properly observable when it covers all three pillars.

Health Checks

• /actuator/health returns UP when all critical dependencies are reachable
• Each HealthIndicator is fast (under 100ms) and handles timeouts gracefully
• Health endpoint is included in Kubernetes readiness probes
• Liveness probe does not depend on external systems

Metrics

• JVM memory, GC, and thread metrics are available at /actuator/metrics
• HTTP request latency and throughput are recorded by default
• Custom business metrics are registered for key operations
• No high-cardinality tags are used on metrics (avoid userId, sessionId, requestId as tags)
• Metrics are exported to your monitoring backend (Prometheus, Datadog, etc.)
• Alerts are configured for metric thresholds

Traces

• Distributed tracing is enabled if your service calls other microservices (see the Microservices roadmap for the full picture)
• Trace IDs are propagated through HTTP headers and message queue metadata
• Slow requests are traceable back to specific operations

Securing Actuator Endpoints

Spring Security integrates with Actuator through the EndpointRequest matcher. Here is a config that requires authentication for all actuator endpoints and assigns role-based restrictions to specific endpoints.

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration
@EnableWebSecurity
public class ActuatorSecurityConfig {

    @Bean
    public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint());
        http.authorizeHttpRequests(requests -> requests
            .requestMatchers(EndpointRequest.to("/health", "/info")).permitAll()
            .requestMatchers(EndpointRequest.to("/prometheus")).hasRole("METRICS_VIEWER")
            .requestMatchers(EndpointRequest.toAnyEndpoint()).hasRole("ENDPOINT_ADMIN")
        );
        http.httpBasic(withDefaults());
        return http.build();
    }
}

A few things worth remembering:

• /health and /info are publicly accessible by default. This is intentional – load balancers and orchestrators need to reach them without authentication.
• Always audit /env, /configprops, /heapdump, and /threaddump before enabling them.
• Use management.endpoints.web.exposure.include and .exclude to explicitly list which endpoints should be reachable over HTTP.
• Set management.endpoint.env.show-values to never or when-authorized to control whether sensitive values appear in responses.
• In air-gapped environments, disable actuator web exposure entirely and rely only on JMX. Pair this with a solid API versioning strategy so your services remain manageable without external monitoring.

Common Pitfalls / Anti-Patterns

Metric Naming Inconsistencies. Micrometer recommends dot-separated names: orders.processed, orders.pending, order.processing.time. Mixing camelCase and underscores across your metrics makes dashboards and alerts harder to maintain.

Forgetting the Unit in the Name. Micrometer encodes units in its metadata separately. Do not encode the unit in the metric name itself. orderProcessingTimeMillis redundantly puts the unit in the name. Just use order.processing.time and Micrometer handles the rest.

Slow Health Indicators. The /health endpoint waits for every registered health indicator to respond. If one is slow, the entire endpoint is slow. Set timeouts on any network call inside a HealthIndicator.

Enabling Too Many Endpoints in Production. Setting management.endpoints.web.exposure.include=* in production is an open invitation for information disclosure. Name exactly the endpoints you need.

Missing Metric Tags for Context. http.requests with no tags tells you nothing. Add uri, method, status tags so you can actually filter and group in your dashboards.

Production Failure Scenarios

Actuator endpoints misbehave in ways that are hard to predict until production traffic hits them.

Metrics Endpoint Overload from High Cardinality Tags

Attaching high-cardinality tags like userId, sessionId, or requestId to metrics creates an unbounded explosion of time series in Prometheus. Each unique tag combination becomes a separate metric. Under load with thousands of users, this overwhelms Prometheus storage and can slow your application as the MeterRegistry grows without bound. The fix is strict tag cardinality control: only tag with values that have a small fixed set of possibilities like environment, region, status_code, or endpoint. For user or session-level tracking, use distributed traces or structured logs instead.

Health Endpoint Blocking During Dependency Outage

If a HealthIndicator makes a network call to an external service with a long timeout, /health blocks until that call succeeds or times out. During a genuine outage of that dependency, the health check itself becomes the problem. Your load balancer sees the health endpoint as slow and marks the instance as unhealthy even when the application would recover on its own. The cascade follows: healthy instances get traffic, fail health checks, more traffic shifts to remaining healthy instances, those fail under load, and the system rolls over. Keep health indicators fast and local. Set timeouts in the hundreds of milliseconds. For external dependency checks, use circuit breakers that fail fast rather than waiting.

Endpoint ID Collision Silently Breaking Monitoring

Defining a custom @Endpoint(id = “metrics”) that conflicts with the built-in metrics endpoint does not produce a warning at startup. Spring Boot silently lets your endpoint win some of the time and the built-in win the rest, depending on registration order. You may not notice until your dashboards go blank or your custom endpoint starts receiving traffic meant for the built-in one. Avoid endpoint IDs that overlap with built-ins: health, info, metrics, prometheus, loggers, env, beans, caches, threaddump, heapdump. If you need custom metrics exposure, register them through MeterRegistry rather than as a separate endpoint.

Security Misconfiguration Exposing Sensitive Data

Publishing /env or /configprops without auditing what they contain is an information disclosure waiting to happen. Spring Boot sanitizes known sensitive property names by default, but custom properties with names that do not match the sanitization patterns slip through. An attacker who retrieves the full environment can often find database passwords, API keys, or internal hostnames. Always set management.endpoint.env.show-values to never or when-authorized. Audit /env and /configprops before enabling them in any environment that external traffic can reach. In production, restrict these endpoints to internal networks or disable their web exposure entirely.

Quick Recap Checklist

The essential points about Spring Boot Actuator:

• Only /health is exposed over HTTP by default. Use management.endpoints.web.exposure.include to whitelist the others.
• Build custom endpoints with @Endpoint, @ReadOperation, @WriteOperation, and @DeleteOperation.
• Health indicators implement HealthIndicator – keep them fast and resilient.
• Micrometer is the facade between your code and your monitoring backend.
• @Timed, @Gauge, and @Counter let you instrument code with minimal boilerplate.
• High-cardinality tag values cause memory leaks and can overwhelm your metrics backend. Keep tags bounded.
• Secure actuator endpoints with Spring Security or network controls before exposing them over HTTP.
• /env and /configprops can leak sensitive config. Audit them before enabling.

Interview Questions

Further Reading

• Spring Boot Actuator Reference – Official documentation for all available endpoints and their configuration options.
• Micrometer Documentation – Deep reference for the metrics facade, including all supported backends and annotation reference.
• Micrometer: Meter Registries – Specific guides for Prometheus, Datadog, Elastic, InfluxDB, and other supported monitoring systems.
• Spring Boot Actuator with Micrometer – Spring.io tutorial covering the integration points and common configurations.
• Custom Health Indicators in Spring Boot – Baeldung guide with examples of reactive and custom health checks.
• Kubernetes Probes and Spring Boot – How Actuator health endpoints map to Kubernetes liveness and readiness probes.

Conclusion

Spring Boot Actuator and Micrometer together form the observability backbone of production Spring Boot applications. Actuator exposes operational endpoints that reveal the internal state of your running application, while Micrometer provides a vendor-neutral API for instrumenting your code with meaningful metrics. The default security posture is conservative – only /health is exposed publicly – which is the right starting point, but every production deployment requires deliberate configuration of which additional endpoints to expose and how to secure them.

The most impactful habits to build: instrument your custom business operations with Micrometer counters, timers, and gauges before production breaks, keep health indicators fast and local to prevent cascading failures during upstream outages, and enforce tag cardinality discipline from the start. High-cardinality tags do not show up in development – they surface as Prometheus OOM events at 3 AM. The investment in proper observability infrastructure pays back immediately when incidents become short and well-understood rather than long and mysterious.