Configuration, Profiles & Actuator

Introduction to Spring Boot Actuator

18 min Lesson 6 of 13

Introduction to Spring Boot Actuator

You have built the application — now how do you know it is running well? In production you need answers to questions like: Is the database connection alive? How much heap is the JVM consuming? How many HTTP requests has the server processed? Spring Boot Actuator answers all of these questions without any bespoke code on your part. It exposes a set of HTTP endpoints (and JMX beans) that surface the operational state of your application at runtime.

What Actuator Is

Actuator is a first-class Spring Boot module — a dependency you add once and an entire suite of endpoints appears. These endpoints are commonly called management endpoints and each one reveals a specific slice of operational data: health, metrics, environment variables, thread dumps, configuration beans, HTTP trace, and more. Rather than writing a custom /healthcheck route that pings the database, you get a battle-tested, pluggable implementation for free.

Production operations vs. development debugging: Actuator endpoints are designed for operations teams, monitoring agents (Prometheus, Datadog, New Relic), load balancers, and container orchestrators (Kubernetes liveness/readiness probes). They are not primarily a developer convenience — they are a production requirement in any serious deployment.

Adding Actuator to a Project

Add the starter to pom.xml (or the Gradle equivalent):

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

That is the only change required to enable Actuator. When the application starts you will see log lines like:

Exposing 1 endpoint(s) beneath base path '/actuator'

Only /actuator/health is exposed over HTTP by default. This conservative default is deliberate — some endpoints leak sensitive data and must be explicitly turned on.

Core Endpoints at a Glance

Actuator ships with over a dozen built-in endpoints. The most important ones for day-to-day production operations are:

/actuator/health — Aggregated health status (UP / DOWN / OUT_OF_SERVICE). Checks database, disk space, message brokers, and any custom indicator you register. This is what Kubernetes points its liveness and readiness probes at.
/actuator/info — Arbitrary application metadata: build version, git commit, environment properties. Populated from application.properties or application.yml under the info.* namespace.
/actuator/metrics — Micrometer-powered metrics registry. Lists available metric names; drill into /actuator/metrics/{name} for values. Covers JVM memory, GC pauses, HTTP request counts, and more.
/actuator/env — The resolved Environment — every property source (system properties, environment variables, application.yml) and their effective values. Sensitive values are masked by default.
/actuator/beans — The full list of Spring beans registered in the application context, their types, and dependencies.
/actuator/mappings — Every @RequestMapping registered, including its handler method. Invaluable when debugging routing surprises.
/actuator/loggers — View and dynamically change log levels at runtime without restarting the application.
/actuator/threaddump — A snapshot of all JVM threads and their current stack traces. The first tool to reach for when diagnosing a deadlock or runaway thread.
/actuator/httptrace (renamed /actuator/httpexchanges in Spring Boot 3) — The last N HTTP request/response pairs. Requires a registered HttpExchangeRepository bean.
/actuator/shutdown — Gracefully stops the application via a POST request. Disabled by default and should stay that way on any publicly reachable server.

Enabling and Exposing Endpoints

Actuator distinguishes between an endpoint being enabled (the feature is active) and being exposed (reachable over HTTP or JMX). An endpoint can be enabled but not exposed. The default strategy is intentionally restrictive:

All endpoints are enabled by default except shutdown.
Only health is exposed over HTTP by default.
All endpoints are exposed over JMX by default (if JMX is on).

To expose additional endpoints, use management.endpoints.web.exposure.include:

# application.properties

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

# Or expose everything (common in internal/dev environments — review security before production)
management.endpoints.web.exposure.include=*

# Explicitly exclude shutdown even when using wildcard
management.endpoints.web.exposure.exclude=shutdown

Never expose all endpoints on a public-facing port without authentication. Endpoints like /actuator/env and /actuator/beans can expose configuration values, class paths, and internal wiring that an attacker can exploit. Lesson 9 in this tutorial covers securing Actuator with Spring Security.

The Base Path and a Separate Management Port

By default, Actuator mounts all endpoints under /actuator. You can relocate this prefix:

# Move to /ops
management.endpoints.web.base-path=/ops

For internal services it is common practice to serve the management endpoints on a completely separate port that is unreachable from the public internet — only reachable inside the Kubernetes cluster or VPC:

# Serve management endpoints on port 8081
management.server.port=8081

# Bind management only to localhost (not the public NIC)
management.server.address=127.0.0.1

This is one of the cleanest architectural patterns for Actuator in production: your application serves traffic on port 8080 (or 443 behind a proxy), and your monitoring infrastructure calls port 8081 which is firewalled from the outside world.

How Actuator Integrates With the Rest of Your Stack

Actuator does not operate in isolation — it is designed to be consumed:

Kubernetes — Configure livenessProbe and readinessProbe to call /actuator/health/liveness and /actuator/health/readiness (Spring Boot 3 splits these automatically when deployed in a Kubernetes environment).
Prometheus / Grafana — Add micrometer-registry-prometheus and Prometheus scrapes /actuator/prometheus; Grafana displays dashboards. No extra code needed beyond the dependency.
Log aggregators — /actuator/loggers lets you raise a log level to DEBUG on a live node to capture a specific failure, then lower it back — without a restart.

Use the info endpoint to surface your build version. Add the spring-boot-maven-plugin build-info goal and your CI pipeline's git commit SHA. When an incident occurs, /actuator/info tells you exactly which build and which commit is running — invaluable in a fleet of containers where image tags may be ambiguous.

# application.properties — expose git commit and build info in /actuator/info
management.info.git.mode=full
management.info.build.enabled=true

info.app.name=order-service
info.app.team=platform

Summary

Spring Boot Actuator turns your application into a self-describing, observable service. With a single dependency you gain health checks, environment inspection, runtime metrics, live log-level changes, and thread dumps — everything an operations team needs to run and troubleshoot a service in production. The key discipline is knowing which endpoints to expose and how to protect them: by default only /actuator/health is visible, and for good reason. The subsequent lessons in this tutorial build on that foundation — customising health indicators, publishing Micrometer metrics, and locking down the management surface with Spring Security.