Spring Boot Actuator – Monitoring, Health Checks and Metrics

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

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

{
  "_links": {
    "self":          { "href": "http://localhost:8080/actuator", "templated": false },
    "health":        { "href": "http://localhost:8080/actuator/health", "templated": false },
    "health-path":   { "href": "http://localhost:8080/actuator/health/{*path}", "templated": true }
  }
}

# Expose these endpoints over HTTP
management.endpoints.web.exposure.include=health,info,metrics,loggers

# Never expose these, even if "include" matches them
management.endpoints.web.exposure.exclude=env,beans

# Turn every endpoint off unless it is listed below
management.endpoints.access.default=none

# Allow reading only
management.endpoint.health.access=read-only
management.endpoint.info.access=read-only
management.endpoint.metrics.access=read-only

# Allow reading and changing log levels
management.endpoint.loggers.access=unrestricted

# /actuator/health becomes /actuator/healthcheck
management.endpoints.web.path-mapping.health=healthcheck

{
  "status": "UP"
}

# never (default) | when-authorized | always
management.endpoint.health.show-details=when-authorized
management.endpoint.health.roles=ADMIN

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": { "database": "PostgreSQL", "validationQuery": "isValid()" }
    },
    "diskSpace": {
      "status": "UP",
      "details": { "total": 499963174912, "free": 91493904384, "threshold": 10485760, "exists": true }
    },
    "ping": { "status": "UP" }
  }
}

# Do not check the mail server
management.health.mail.enabled=false

package com.example.shop.health;

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

import com.example.shop.payment.PaymentGatewayClient;

@Component
public class PaymentGatewayHealthIndicator implements HealthIndicator {

    private final PaymentGatewayClient client;

    public PaymentGatewayHealthIndicator(PaymentGatewayClient client) {
        this.client = client;
    }

    @Override
    public Health health() {
        long start = System.currentTimeMillis();
        try {
            boolean reachable = client.ping();
            long tookMs = System.currentTimeMillis() - start;

            if (reachable) {
                return Health.up()
                        .withDetail("responseTimeMs", tookMs)
                        .build();
            }
            return Health.down()
                    .withDetail("reason", "Gateway did not answer the ping")
                    .build();

        } catch (Exception ex) {
            // Health.down(ex) adds the error message to the details
            return Health.down(ex).build();
        }
    }
}

"paymentGateway": {
  "status": "UP",
  "details": { "responseTimeMs": 42 }
}

# /actuator/health/core checks only the database and disk
management.endpoint.health.group.core.include=db,diskSpace
management.endpoint.health.group.core.show-details=always

management.endpoint.health.probes.enabled=true

# Optional: add the database check to readiness
management.endpoint.health.group.readiness.include=readinessState,db

livenessProbe:
  httpGet:
    path: /actuator/health/liveness
    port: 8080
  initialDelaySeconds: 20
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /actuator/health/readiness
    port: 8080
  periodSeconds: 5

package com.example.shop.catalog;

import org.springframework.boot.availability.AvailabilityChangeEvent;
import org.springframework.boot.availability.ReadinessState;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.stereotype.Component;

@Component
public class CacheReloader {

    private final ApplicationEventPublisher publisher;
    private final ProductCache productCache;

    public CacheReloader(ApplicationEventPublisher publisher, ProductCache productCache) {
        this.publisher = publisher;
        this.productCache = productCache;
    }

    public void reload() {
        // Stop receiving traffic while the cache is empty
        AvailabilityChangeEvent.publish(publisher, this, ReadinessState.REFUSING_TRAFFIC);
        try {
            productCache.reloadAll();
        } finally {
            // Accept traffic again, even if the reload failed
            AvailabilityChangeEvent.publish(publisher, this, ReadinessState.ACCEPTING_TRAFFIC);
        }
    }
}

management.info.env.enabled=true
info.app.name=Order Service
info.app.description=Takes and tracks customer orders
info.app.team=checkout-team@example.com

# Add Java and operating system details
management.info.java.enabled=true
management.info.os.enabled=true

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>build-info</goal>
            </goals>
        </execution>
    </executions>
</plugin>

<!-- Adds the Git branch and commit to /actuator/info -->
<plugin>
    <groupId>io.github.git-commit-id</groupId>
    <artifactId>git-commit-id-maven-plugin</artifactId>
</plugin>

{
  "app": {
    "name": "Order Service",
    "description": "Takes and tracks customer orders",
    "team": "checkout-team@example.com"
  },
  "build": {
    "artifact": "order-service",
    "version": "2.4.1",
    "time": "2026-10-01T09:15:42Z"
  },
  "git": {
    "branch": "main",
    "commit": { "id": "4f9c2ab", "time": "2026-09-30T17:02:11Z" }
  }
}

package com.example.shop.info;

import java.util.Map;

import org.springframework.boot.actuate.info.Info;
import org.springframework.boot.actuate.info.InfoContributor;
import org.springframework.stereotype.Component;

@Component
public class FeatureFlagsInfoContributor implements InfoContributor {

    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("features", Map.of(
                "newCheckout", true,
                "giftCards", false));
    }
}

# List every metric name
curl http://localhost:8080/actuator/metrics

# Look at one metric
curl http://localhost:8080/actuator/metrics/jvm.memory.used

# Narrow it down with tags: successful calls to /orders only
curl "http://localhost:8080/actuator/metrics/http.server.requests?tag=uri:/orders&tag=status:200"

{
  "name": "http.server.requests",
  "baseUnit": "seconds",
  "measurements": [
    { "statistic": "COUNT",      "value": 1520 },
    { "statistic": "TOTAL_TIME", "value": 63.84 },
    { "statistic": "MAX",        "value": 0.412 }
  ],
  "availableTags": [
    { "tag": "method", "values": ["GET", "POST"] },
    { "tag": "status", "values": ["200", "201", "400"] }
  ]
}

package com.example.shop.order;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import org.springframework.stereotype.Service;

@Service
public class OrderService {

    private final OrderRepository repository;
    private final MeterRegistry registry;
    private final Counter ordersPlaced;
    private final Timer checkoutTimer;
    private final Map<String, Cart> activeCarts = new ConcurrentHashMap<>();

    public OrderService(OrderRepository repository, MeterRegistry registry) {
        this.repository = repository;
        this.registry = registry;

        this.ordersPlaced = Counter.builder("shop.orders.placed")
                .description("Number of orders placed")
                .register(registry);

        this.checkoutTimer = Timer.builder("shop.checkout.duration")
                .description("Time taken to complete a checkout")
                .register(registry);

        // A gauge reads the current size of the map whenever it is scraped
        Gauge.builder("shop.carts.active", activeCarts, Map::size)
                .description("Shopping carts currently open")
                .register(registry);
    }

    public Order placeOrder(OrderRequest request) {
        return checkoutTimer.record(() -> {
            Order order = repository.save(Order.from(request));
            ordersPlaced.increment();
            activeCarts.remove(request.cartId());
            return order;
        });
    }

    public void recordFailedPayment(String paymentMethod) {
        // A tag splits one metric into a few groups, such as card or wallet
        registry.counter("shop.payments.failed", "method", paymentMethod).increment();
    }
}

management.metrics.tags.application=order-service
management.metrics.tags.environment=production

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

management.endpoints.web.exposure.include=health,info,prometheus
management.metrics.distribution.percentiles-histogram.http.server.requests=true

# HELP shop_orders_placed_total Number of orders placed
# TYPE shop_orders_placed_total counter
shop_orders_placed_total{application="order-service",environment="production"} 128.0

scrape_configs:
  - job_name: "order-service"
    metrics_path: "/actuator/prometheus"
    scrape_interval: 15s
    static_configs:
      - targets: ["order-service:8080"]

# Check the current level for a package
curl http://localhost:8080/actuator/loggers/com.example.shop.order

# Switch it to DEBUG
curl -X POST http://localhost:8080/actuator/loggers/com.example.shop.order \
     -H "Content-Type: application/json" \
     -d '{"configuredLevel": "DEBUG"}'

# Go back to the configured default
curl -X POST http://localhost:8080/actuator/loggers/com.example.shop.order \
     -H "Content-Type: application/json" \
     -d '{"configuredLevel": null}'

{
  "configuredLevel": "DEBUG",
  "effectiveLevel": "DEBUG"
}

package com.example.shop.actuator;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

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

@Component
@Endpoint(id = "features")
public class FeaturesEndpoint {

    private final Map<String, Boolean> features = new ConcurrentHashMap<>(
            Map.of("newCheckout", true, "giftCards", false));

    // GET /actuator/features
    @ReadOperation
    public Map<String, Boolean> all() {
        return features;
    }

    // GET /actuator/features/{name}  (returning null gives a 404)
    @ReadOperation
    public Boolean one(@Selector String name) {
        return features.get(name);
    }

    // POST /actuator/features/{name}  with body {"enabled": true}
    @WriteOperation
    public void update(@Selector String name, boolean enabled) {
        features.put(name, enabled);
    }

    // DELETE /actuator/features/{name}
    @DeleteOperation
    public void remove(@Selector String name) {
        features.remove(name);
    }
}

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

package com.example.shop.config;

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.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                // Health and info are public
                .requestMatchers(EndpointRequest.to("health", "info")).permitAll()
                // Every other Actuator endpoint needs the ADMIN role
                .requestMatchers(EndpointRequest.toAnyEndpoint()).hasRole("ADMIN")
                // The rest of the application needs a logged-in user
                .anyRequest().authenticated()
            )
            // Allow POST to endpoints like /actuator/loggers from tools such as curl
            .csrf(csrf -> csrf.ignoringRequestMatchers(EndpointRequest.toAnyEndpoint()))
            .httpBasic(Customizer.withDefaults());

        return http.build();
    }
}

management.server.port=9090

# Optional: listen only on the local network interface
management.server.address=127.0.0.1

management.endpoints.web.base-path=/manage

# never (default) | when-authorized | always
management.endpoint.env.show-values=when-authorized
management.endpoint.configprops.show-values=when-authorized

# Which endpoints are visible over HTTP
management.endpoints.web.exposure.include=health,info,metrics,prometheus,loggers

# Health details and Kubernetes probes
management.endpoint.health.show-details=when-authorized
management.endpoint.health.probes.enabled=true

# Info
management.info.env.enabled=true
management.info.git.mode=full

# Separate port and custom path
management.server.port=9090
management.endpoints.web.base-path=/manage

# Add common tags to all metrics
management.metrics.tags.application=my-shop-service
management.metrics.tags.environment=production

# Show configuration values only to authorized users
management.endpoint.env.show-values=when-authorized
management.endpoint.configprops.show-values=when-authorized

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus,loggers
      base-path: /manage
  endpoint:
    health:
      show-details: when-authorized
      probes:
        enabled: true
  server:
    port: 9090
  metrics:
    tags:
      application: my-shop-service
      environment: production

package com.example.shop.health;

import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;

import org.junit.jupiter.api.Test;
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.Status;

import com.example.shop.payment.PaymentGatewayClient;

class PaymentGatewayHealthIndicatorTest {

    private final PaymentGatewayClient client = mock(PaymentGatewayClient.class);
    private final PaymentGatewayHealthIndicator indicator = new PaymentGatewayHealthIndicator(client);

    @Test
    void reportsUpWhenGatewayAnswers() {
        when(client.ping()).thenReturn(true);

        Health health = indicator.health();

        assertThat(health.getStatus()).isEqualTo(Status.UP);
        assertThat(health.getDetails()).containsKey("responseTimeMs");
    }

    @Test
    void reportsDownWhenGatewayThrows() {
        when(client.ping()).thenThrow(new IllegalStateException("Connection timed out"));

        Health health = indicator.health();

        assertThat(health.getStatus()).isEqualTo(Status.DOWN);
    }
}

package com.example.shop;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.security.test.context.support.WithMockUser;
import org.springframework.test.web.servlet.MockMvc;

@SpringBootTest
@AutoConfigureMockMvc
class ActuatorSecurityTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void healthIsPublic() throws Exception {
        mockMvc.perform(get("/actuator/health"))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$.status").value("UP"));
    }

    @Test
    void metricsRejectAnonymousUsers() throws Exception {
        mockMvc.perform(get("/actuator/metrics"))
               .andExpect(status().isUnauthorized());
    }

    @Test
    @WithMockUser(roles = "ADMIN")
    void adminCanReadMetrics() throws Exception {
        mockMvc.perform(get("/actuator/metrics"))
               .andExpect(status().isOk());
    }
}