Monitoring with Actuator

Reviewed & published by Brayan K

Spring Boot Actuator bolts production-ready endpoints onto your app — /actuator/health, /actuator/metrics, /actuator/info — with Micrometer collecting metrics you can export anywhere.

Part of the free Java course at LearnCodingFast — hands-on lessons with worked examples and the output they print, plus practice exercises and a quick quiz.

Before You Start

You should be comfortable building a Spring Boot app and tweaking its configuration and profiles. Knowing a little about HTTP endpoints and JSON helps when reading the responses.

What You'll Learn

• What Actuator adds to a Spring Boot app
• The /health, /metrics, and /info endpoints
• How health status aggregates component checks
• How Micrometer collects counters and gauges
• Exposing endpoints with exposure.include
• Securing sensitive endpoints in production

The Big Idea — The Dashboard of Your Application

💡 Analogy: Actuator is the dashboard and warning lights of your application, like a car's instrument cluster. /actuator/health is the big green "all systems go" light — and if the oil, brakes, or engine (any component) fails, it flips to red. /actuator/metrics is the set of gauges: speed, RPM, fuel — live numbers about how hard the engine is working. /actuator/info is the little plate showing the model and build. And just as you don't let strangers pop the hood and read the diagnostics port, you lock down the sensitive endpoints in production.

You don't build the dashboard yourself — Actuator wires it in; you just choose which gauges to show and to whom.

1️⃣ /health — Aggregated Status

The health endpoint combines many component checks into one status: if any indicator is DOWN, the whole app reports DOWN. The plain-Java model below shows that aggregation rule.

import java.util.*;

public class Main {
    // /actuator/health AGGREGATES many component checks into one status: if ANY
    // component is DOWN, the whole app is DOWN. We model that aggregation in
    // plain Java so the health-endpoint logic is concrete.
    interface HealthIndicator { String name(); boolean up(); }

    static String overall(List<HealthIndicator> checks) {
        boolean allUp = checks.stream().allMatch(HealthIndicator::up);
        return allUp ? "UP" : "DOWN";
    }

    public static void main(String[] args) {
        List<HealthIndicator> checks = List.of(
            indicator("db",   true),
            indicator("disk", true),
            indicator("mail", false)   // one downstream is unhealthy
        );

        System.out.println("overall: " + overall(checks));
        for (HealthIndicator h : checks) {
            System.out.println("  " + h.name() + ": " + (h.up() ? "UP" : "DOWN"));
        }
    }

    static HealthIndicator indicator(String n, boolean up) {
        return new HealthIndicator() {
            public String name() { return n; }
            public boolean up()  { return up; }
        };
    }
}

2️⃣ /metrics — Counters and Gauges

Metrics are collected by Micrometer. The core meter types are counters (ever-increasing totals, like request counts) and gauges (live values, like active sessions). The demo builds tiny versions to show what a registry holds.

import java.util.*;
import java.util.concurrent.atomic.*;

public class Main {
    // Micrometer's two core meter types: COUNTERS (monotonic totals) and GAUGES
    // (current values). Actuator's /actuator/metrics surfaces exactly these. We
    // build tiny versions to show what a metric registry actually holds.
    static class Counter {
        private final AtomicLong count = new AtomicLong();
        void increment() { count.incrementAndGet(); }
        long value() { return count.get(); }
    }

    public static void main(String[] args) {
        Map<String, Counter> registry = new LinkedHashMap<>();
        Counter requests = new Counter();
        registry.put("http.server.requests", requests);

        // Simulate handling some requests.
        for (int i = 0; i < 5; i++) requests.increment();

        // A gauge reads a live value (e.g. active sessions).
        int activeSessions = 3;

        System.out.println("counter http.server.requests = " + requests.value());
        System.out.println("gauge   active.sessions       = " + activeSessions);
        System.out.println("registry has metrics: " + registry.keySet());
    }
}

3️⃣ Exposing Endpoints

By default only health (and info) are exposed over HTTP. You opt into more with management.endpoints.web.exposure.include and can enrich /info with build metadata.

management.endpoints.web.exposure.include=health,info,metrics
management.endpoint.health.show-details=when-authorized

# application.properties — exposing Actuator endpoints (needs
# spring-boot-starter-actuator on the classpath).

# By default only 'health' (and 'info') are exposed over HTTP. Opt in to more:
management.endpoints.web.exposure.include=health,info,metrics

# Show full health details (component breakdown) — guard this in production!
management.endpoint.health.show-details=when-authorized

# Populate /actuator/info from build + git metadata.
management.info.env.enabled=true
info.app.name=Orders API
info.app.version=1.4.0

# Then, with the app running, these URLs work:
#   GET /actuator/health   -> {"status":"UP"}
#   GET /actuator/info     -> {"app":{"name":"Orders API","version":"1.4.0"}}
#   GET /actuator/metrics  -> {"names":["http.server.requests", ...]}
#   GET /actuator/metrics/http.server.requests -> measurements for that metric

4️⃣ Adding a Custom HealthIndicator

Implement HealthIndicator to fold your own check (a downstream service, a queue, a license) into /actuator/health — the same aggregation you saw in section 1.

🧠 Quick Recall

Predict before you peek.

Answer: DOWN — the overall status aggregates components and fails if any one fails.

Answer: Micrometer — a vendor-neutral facade that exports to many monitoring backends.

Answer: add it to management.endpoints.web.exposure.include (it isn't exposed by default).

🎯 YOUR TURN — Health Aggregation

Write overall(components) returning "UP" only when every component is up.

import java.util.*;

public class Main {
    // YOUR TURN: implement the health AGGREGATION rule.
    // Write overall(Map<String,Boolean> components) that returns "UP" only when
    // EVERY component is up, otherwise "DOWN".
    //
    // Expected output:
    //   all up   -> UP
    //   one down -> DOWN

    // static String overall(Map<String,Boolean> components) { ... }

    public static void main(String[] args) {
        // System.out.println("all up   -> " + overall(Map.of("db", true, "disk", true)));
        // System.out.println("one down -> " + overall(Map.of("db", true, "disk", false)));
    }
}

🧩 MINI-CHALLENGE — A Tiny Metrics Registry

Build a named-counter registry like Micrometer: increment by name, then print all metrics sorted.

import java.util.*;
import java.util.concurrent.atomic.*;

public class Main {
    // MINI-CHALLENGE: a tiny metrics registry like Micrometer. Support named
    // counters: increment a counter by name (creating it on first use) and then
    // expose all metric names and values, sorted by name.
    //
    // Expected output:
    //   logins=2
    //   orders=3

    static Map<String, AtomicLong> registry = new TreeMap<>();

    static void increment(String name) {
        // get-or-create the counter for 'name' and increment it
    }

    public static void main(String[] args) {
        // increment "orders" 3 times and "logins" twice
        // then print each "name=value" sorted
    }
}

Common Errors

• ❌ Expecting all endpoints by default. Only health/info are exposed over HTTP. Fix: add others to exposure.include.
• ❌ Exposing everything with * in production. Leaks sensitive data. Fix: expose only what you need and secure it.
• ❌ Showing full health details publicly. Reveals internals. Fix: show-details=when-authorized.
• ❌ Forgetting the starter dependency. No endpoints appear. Fix: add spring-boot-starter-actuator.
• ❌ Confusing counters and gauges. Counters only increase. Fix: use a gauge for values that go up and down.
• ❌ Leaving heapdump/threaddump open. DoS and disclosure risk. Fix: restrict to an internal management port.

Pro Tips

• 💡 Use /actuator/health for liveness/readiness probes in Kubernetes and load balancers.
• 💡 Export metrics to Prometheus by adding the Micrometer Prometheus registry — no code changes needed.
• 💡 Run Actuator on a separate management port (management.server.port) to isolate it from public traffic.
• 💡 Add custom HealthIndicators for critical downstreams so a failure surfaces immediately.

📋 Quick Reference

📚 Resources / Keep Learning

• 📘 Actuator — Spring Boot reference
• 📗 Micrometer documentation
• 📗 Building a RESTful Web Service with Actuator — Spring guide

🎉 Lesson Complete!

You now know what Actuator adds, how /health aggregates component checks, how Micrometer collects counters and gauges behind /metrics, how to expose endpoints with exposure.include, and why sensitive endpoints must be secured in production.

Practice quiz

Continue this course

• Previous: Testing the Data Layer
• Next: Caching with @Cacheable — @EnableCaching, @Cacheable/@CacheEvict and cache providers
• Quick reference: Java cheat sheet

Frequently asked questions

What is Spring Boot Actuator and why use it?

Actuator is a Spring Boot module that adds production-ready endpoints for monitoring and managing a live application. Once you add spring-boot-starter-actuator, you get ready-made HTTP (and JMX) endpoints such as /actuator/health, /actuator/metrics, /actuator/info, /actuator/env, and more — no code required. It saves you from hand-building health checks and metrics plumbing, and it integrates with monitoring systems, so operators can see at a glance whether the app is healthy and how it is behaving under load.

What does the /actuator/health endpoint actually report?

The health endpoint reports an overall status — typically UP or DOWN — that aggregates a set of health indicators. Spring Boot ships indicators for common components (datasource, disk space, message brokers, and so on), and the overall status is DOWN if any contributing component is DOWN. You can show a detailed breakdown of each component (gated behind configuration for safety), and you can add your own custom HealthIndicator to fold a downstream dependency's status into the result. This is what load balancers and orchestrators often probe to decide if an instance should receive traffic.

How does Actuator collect metrics, and what is Micrometer?

Actuator's metrics are powered by Micrometer, a vendor-neutral metrics facade — think of it as SLF4J but for metrics. You (and Spring Boot's auto-configuration) record meters such as counters (monotonically increasing totals like request counts), gauges (current values like active connections), and timers (latency distributions). Micrometer then exports those same meters to whatever monitoring backend you configure — Prometheus, Datadog, New Relic, and others — so you instrument once and ship the data anywhere. The /actuator/metrics endpoint lets you browse them over HTTP.

How do I expose Actuator endpoints, and which are exposed by default?

For safety, recent Spring Boot exposes only a minimal set over HTTP by default (health, and info). To expose more, set management.endpoints.web.exposure.include in your configuration — for example health,info,metrics, or * for everything (not advisable in production). You can also change the base path or move endpoints to a separate management port. The principle is least exposure: turn on only what you need, because some endpoints are powerful or sensitive.

Why must I be careful with Actuator endpoints in production?

Several endpoints can reveal internal details or perform powerful operations: /actuator/env and /actuator/configprops can expose configuration (potentially including secrets), /actuator/heapdump produces a memory dump, /actuator/threaddump shows thread state, and /actuator/loggers can change log levels at runtime. If these are open to the public, they become an information-disclosure or denial-of-service risk. Best practice is to expose only the endpoints you need, secure them with Spring Security, and ideally serve them on an internal-only management port or network.

Related lessons

• configuration and profiles