What is Spring Boot Actuator?

Spring Boot Actuator is a feature that provides a way to check your application’s “health” and “behavior” from the outside. For example, it lets you retrieve the following information over HTTP:

  • Whether the app is alive (Health Check)
  • Basic application information (Info)
  • Metrics such as memory, threads, and GC (Metrics)
  • Viewing and changing configuration values and log levels (for operations)

It is useful not only for debugging during development, but also as a “foundation” that speeds up monitoring and incident response in production.

Start by Adding the Dependency

Spring Boot Actuator is available simply by adding the starter.

Maven

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

Gradle

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

Once the app is running, try accessing the following URL first:

  • GET /actuator

However, by default only a limited set of endpoints are exposed, so you may not see what you expect. Configure this in the next section.

Configuring Endpoint Exposure

Each Actuator feature is provided as an Endpoint. For security reasons, only the bare minimum is exposed by default.

Here is an example application.yml:

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics

This enables the following:

  • GET /actuator/health
  • GET /actuator/info
  • GET /actuator/metrics

You can quickly verify these with curl:

curl -s http://localhost:8080/actuator/health
curl -s http://localhost:8080/actuator/info
curl -s http://localhost:8080/actuator/metrics

You can use * to expose everything, but this is not recommended in production for security reasons.

management:
  endpoints:
    web:
      exposure:
        include: "*"

Exploring the Most Commonly Used Endpoints

Building Health Checks with Health

/actuator/health is the foundation of monitoring.

curl -s http://localhost:8080/actuator/health

In most cases it returns something like this:

  • status: UP means healthy
  • status: DOWN or OUT_OF_SERVICE means unhealthy

To show more detail, the following configuration is useful:

management:
  endpoint:
    health:
      show-details: when_authorized

Since show-details can lead to information leakage, it is safer to default to when_authorized rather than always.

Returning Application Info with Info

/actuator/info is well-suited for returning “operationally useful information” such as version and build details.

management:
  info:
    env:
      enabled: true

info:
  app:
    name: sample-api
    version: 1.0.0
curl -s http://localhost:8080/actuator/info

Being able to immediately check “which version” is deployed is surprisingly handy.

Viewing Metrics as Numbers with Metrics

/actuator/metrics returns a list of metric names.

curl -s http://localhost:8080/actuator/metrics

To view a specific metric, specify the metric name:

curl -s "http://localhost:8080/actuator/metrics/jvm.memory.used"

The response includes a measurements field containing the current value. For now, confirming that you can retrieve data is enough.

Key Points for Safe Production Use

While Actuator is convenient, exposing it incorrectly can be dangerous. At a minimum, keep the following in mind:

Limit the Exposed Endpoints

Start by only include-ing what you need:

management:
  endpoints:
    web:
      exposure:
        include: health,info

Add metrics if you need them for operations, add prometheus if you use Prometheus — incrementally expanding is the safe approach.

Change the Actuator Base Path

The default is /actuator, but you can change it like this:

management:
  endpoints:
    web:
      base-path: /management

Isolate Actuator on a Dedicated Port

Separating it from the application’s public port makes it easier to protect at the network level.

management:
  server:
    port: 9001

This way, normal API traffic goes through :8080 and Actuator through :9001.

Always Require Authentication

In particular, endpoints like env and configprops can expose configuration values, so be careful about making them public. The basic strategy is simple:

  • Limit the exposure scope
  • Use Spring Security to require authentication if needed
  • Restrict access to the management network only if possible

Combining these three provides solid protection.

Adding Custom Health Checks

You may want to add checks tailored to your application, such as “can we connect to the DB?” or “is the external API responding?”. For this, implement HealthIndicator:

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

@Component
public class ExternalApiHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        boolean ok = pingExternalApi();
        if (ok) {
            return Health.up().withDetail("externalApi", "reachable").build();
        }
        return Health.down().withDetail("externalApi", "unreachable").build();
    }

    private boolean pingExternalApi() {
        // Perform a connectivity check here (short timeout recommended)
        return true;
    }
}

This integrates the result into the /actuator/health response, allowing your monitoring system to quickly identify which component is down.

Connecting to Prometheus for Effortless Monitoring

Actuator integrates with Micrometer and can expose a Prometheus-compatible endpoint. If you use Prometheus, add the following dependency:

Maven

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

Gradle

implementation 'io.micrometer:micrometer-registry-prometheus'

Also add the exposure configuration:

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus

This makes the following available:

  • GET /actuator/prometheus

You can then easily set up a monitoring pipeline where Prometheus scrapes this endpoint periodically and Grafana visualizes the data.

Common Pitfalls

Getting a 404

This is usually caused by one of two things: the endpoint is not exposed, or the base path has been changed.

  • Check management.endpoints.web.exposure.include
  • Check management.endpoints.web.base-path

Health Details Not Showing

This depends on the show-details configuration. Start by setting it to always in your development environment to understand the behavior, then switch back to when_authorized for production.

management:
  endpoint:
    health:
      show-details: always

Production Configuration for Kubernetes

When running on Kubernetes, using separate liveness and readiness probes leads to more stable operation:

management:
  endpoint:
    health:
      probes:
        enabled: true
  endpoints:
    web:
      exposure:
        include: health,info,prometheus

This makes the following endpoints available:

  • GET /actuator/health/liveness
  • GET /actuator/health/readiness

This makes it easier to distinguish states like “the process is running but the DB is unreachable,” reducing restart loops and false positives.

Minimal Exposure Template for Production

To avoid over-exposing endpoints, the following configuration is recommended as a starting point:

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  endpoint:
    health:
      show-details: when_authorized
  server:
    port: 9001

In addition, restrict the management port to internal networks only, and keep it separate from the application’s public port.

Decisions to Make Upfront in Your Monitoring Design

Once Actuator is in place, deciding the following in advance leads to more stable operations:

  • Alert thresholds aligned with your SLO/SLA
  • Which metrics to put on dashboards (CPU, memory, HTTP, error rate)
  • Who to notify during incidents (on-call rules)
  • A process to always update info.app.version with each deployment

Don’t stop at “just getting it set up” — defining your notification and operational workflows is what makes it truly effective.

Summary

Introducing Spring Boot Actuator quickly establishes an “operational entry point” for checking your application’s state from the outside.

  • Start by exposing health and info to build a monitoring foundation
  • Incrementally add metrics and prometheus as needed
  • Design your exposure scope and authentication carefully for production

Getting this far will make incident response and day-to-day operations significantly easier. From here, moving on to topics like “Protecting Actuator with Spring Security” and “Building dashboards with Grafana” will make your setup even more production-ready. Give it a try!