What is Spring Boot Actuator

Quick Setup Reference (spring-boot-starter-actuator)

This is a quick reference for those who want to “just get it running” or “know what to write after adding spring-boot-starter-actuator to expose which endpoints” in the fastest way possible.

1. Dependencies (Maven / Gradle)

<!-- pom.xml -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
// build.gradle
implementation 'org.springframework.boot:spring-boot-starter-actuator'

2. Minimal application.yml (exposing health / info / metrics)

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
  endpoint:
    health:
      show-details: when_authorized

3. List of Commonly Used Endpoints

PathPurposeProduction Exposure Guideline
GET /actuator/healthLiveness monitoring (UP / DOWN)◎ Recommended to expose
GET /actuator/health/livenessProcess liveness check (K8s liveness)◎
GET /actuator/health/readinessAcceptance availability check (K8s readiness)◎
GET /actuator/infoVersion and build information○
GET /actuator/metricsMetrics list (JVM / HTTP / GC, etc.)△ Authentication recommended
GET /actuator/metrics/{name}Individual metric value△ Authentication recommended
GET /actuator/prometheusFor Prometheus scraping△ Restrict to internal network
GET /actuator/envEnvironment variables and configuration values✕ Do not expose
GET /actuator/configprops@ConfigurationProperties list✕ Do not expose
GET /actuator/loggersView/change log levels✕ Do not expose

If you arrived by searching for springboot actuator / spring boot actuator, first confirm that /actuator/health returns {"status":"UP"} using the 3 steps above, then read the rest of this article for a smoother experience.

Spring Boot Actuator is a feature that provides a way to check the “health status” and “operational state” of your application from the outside. For example, you can retrieve the following information via HTTP:

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

It’s very useful not only for debugging during development but also as a “foundation” for speeding up monitoring and incident response in production operations.

Add Dependencies First

Spring Boot Actuator can be used 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 started, try accessing the following URL first:

  • GET /actuator

However, since the endpoints exposed by default are limited, you may not see what you expect. We’ll configure this next.

Configure Endpoint Exposure

Each Actuator feature is provided as an Endpoint. For safety, only the bare minimum is exposed initially.

Here’s an example application.yml:

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

This makes the following available:

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

curl is convenient for verification:

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

If you want to expose everything, you can use *, but this is not recommended for production due to security concerns.

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

Try Out Commonly Used Endpoints

Build Liveness Monitoring with Health

/actuator/health is the basis of monitoring.

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

In most cases, it returns something like this:

  • status: UP means normal
  • status: DOWN or OUT_OF_SERVICE means abnormal

If you want to show details, the following setting is convenient:

management:
  endpoint:
    health:
      show-details: when_authorized

Since show-details can lead to information leakage, it’s safer to use when_authorized as the default instead of always.

Return App Information with Info

/actuator/info is suitable for returning “information you want for operations” such as version and build information.

management:
  info:
    env:
      enabled: true

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

It becomes convenient to quickly check “which version” of what has been deployed—a subtle but useful feature.

View Status as Numbers with Metrics

/actuator/metrics returns a list of metric names.

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

To see individual metrics, specify the metric name:

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

The response includes measurements, which contains the current values. For now, it’s fine if you can confirm that the metrics are “obtainable.”

Points for Using Actuator Safely in Production

While Actuator is convenient, exposing it incorrectly can be dangerous. At a minimum, the following points are recommended:

Limit the Endpoints You Expose

First, only include what you need.

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

It’s safer to gradually increase exposure: add metrics if you need metrics for operations, add prometheus if you use Prometheus, and so on.

Change the Actuator Base Path

The default is /actuator, but if you want to change it, do this:

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

Separate 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 separates regular APIs on :8080 and Actuator on :9001, for example.

Always Apply Authentication

Especially env and configprops can expose configuration values, so be very careful about exposing them. The basic policy is simple:

  • Limit the exposure scope
  • Authenticate with Spring Security if necessary
  • Close it to the management network only if possible

Protecting with this 3-piece set is a solid approach.

Adding Custom Health Checks

You’ll want to add checks tailored to your own application, such as “can connect to the DB” or “does the external API respond.” In such cases, implement a 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 way, it gets incorporated into the result of /actuator/health. The monitoring side can quickly identify “where something is failing.”

Monitoring Becomes Much Easier When Connected to Prometheus

Actuator integrates with Micrometer, and you can also prepare an endpoint for Prometheus. When using Prometheus, add the dependency.

Maven

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

Gradle

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

Add the exposure setting as well.

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

Then you can get:

  • GET /actuator/prometheus

You can easily build a monitoring setup where Prometheus periodically scrapes and Grafana visualizes.

Common Pitfalls

Getting 404 Errors

This is mostly either “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 Are Not Shown

It depends on the show-details setting. First, set it to always only in the development environment to understand the behavior, and then revert it to when_authorized for production—that’s the safe approach.

management:
  endpoint:
    health:
      show-details: always

Practical Configuration for Kubernetes Operations

When operating on Kubernetes, separating liveness and readiness makes things more stable.

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

It becomes easier to distinguish “the process is alive but cannot connect to the DB,” which reduces restart loops and false judgments.

Minimal Exposure Template for Production

To prevent over-exposure, the following configuration is recommended at the start:

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

Additionally, closing the management port to the internal network only and separating it from the application’s public port is safer.

What to Decide First in Monitoring Design

Once you’ve introduced Actuator, deciding the following first will stabilize operations:

  • Alert thresholds aligned with monitoring SLO/SLA
  • Which metrics to put on a dashboard (CPU, memory, HTTP, error rate)
  • Who to notify in case of failure (on-call rules)
  • Operational practice of always updating info.app.version per deployment unit

Instead of ending with “just introducing it,” deciding the notification and operational flow leads to real effectiveness.

Summary

Introducing Spring Boot Actuator quickly sets up an “operational entry point” that allows you to check the application’s state from the outside.

  • First, expose health and info to build the foundation for monitoring
  • Gradually add metrics and prometheus as needed
  • In production, carefully design the exposure scope and authentication

Once you’ve done this, incident response and operations become significantly easier. Next, advancing to “protecting Actuator with Spring Security” or “creating dashboards with Grafana” will make things even more practical. Please make use of it!