A Developer’s Guide to Spring Boot Actuator

Spring Boot Actuator is a sub-project of Spring Boot that adds production-ready features to your application. It provides built-in HTTP endpoints to monitor and manage your service, giving you immediate insights without writing complex custom code.

What Is Spring Boot Actuator and Why You Need It

Imagine deploying a new application into production. How do you know if it started correctly? How much memory is it consuming? What configuration properties is it using? Without the right tools, answering these questions feels like flying a plane without an instrument panel—you're essentially flying blind.

This is where Spring Boot Actuator becomes an indispensable part of your toolkit. It acts as the "cockpit" for your application, offering a standardised way to gain critical observability. It's not just a developer convenience; it's a foundational component for building resilient, manageable, and production-grade software.

A Look Inside Your Application

Think of Actuator's endpoints as the vital gauges on a dashboard. Each one provides a specific, real-time reading about your application's internal state. For instance:

• The /health endpoint is your main status indicator. A simple GET request to /actuator/health will return a JSON response like {"status":"UP"}, which is crucial for load balancers and automated monitoring systems to confirm the service is operational.
• The /metrics endpoint is like your resource gauge. For example, querying /actuator/metrics/jvm.memory.used will show you exactly how much memory the JVM is using in bytes.
• The /env endpoint reveals the environment properties, profiles, and configuration sources your application is actively using. This is useful for debugging configuration issues, for example, checking if a production profile (spring.profiles.active=prod) has been correctly applied.

By exposing this information through simple HTTP requests, Actuator empowers you to monitor, manage, and troubleshoot services with remarkable efficiency. This capability is central to modern software development and operations.

Key Takeaway: Spring Boot Actuator isn't an optional add-on; it's a core tool for operational visibility. It turns a black-box application into a transparent system you can confidently monitor and maintain in a production environment.

Implementing Spring Boot Actuator aligns perfectly with modern DevOps practices, offering essential insights for continuous integration and delivery. For organisations looking to enhance these processes, exploring professional guidance can be beneficial. For instance, some firms offer specialised DevOps consulting to help optimise development and operations workflows.

Exploring Key Actuator Endpoints with Practical Examples

Once you have Spring Boot Actuator included in your project, you gain a powerful set of built-in endpoints. These aren’t just abstract features; they give you a live, operational view into your application's health, metrics, and configuration. Let's walk through some of the most essential endpoints with practical examples to see exactly what they do.

The most fundamental endpoint is /health. Its job is simple: provide an immediate status check. Automated systems like load balancers and container orchestrators rely on this endpoint to decide if an application instance is healthy enough to handle traffic.

A quick request to /actuator/health will usually give you a straightforward JSON response.

{
  "status": "UP"
}

This "UP" status is the green light for monitoring tools, telling them everything is running as it should. If a critical dependency, like a database connection, were to fail, the status would flip to "DOWN", signalling that the instance needs to be pulled from service. This automated feedback loop is what helps you build resilient, self-healing systems.

Application Information and Metrics

Next up is the /info endpoint. Think of this as your application’s digital nameplate, designed to display static, build-time information. It’s the perfect place to expose details like the application version, a brief description, or even the specific Git commit running in an environment. This is incredibly useful for quickly confirming which version of your code is deployed.

By adding a few properties to your application.properties file, you can populate this endpoint.

info.app.name=My Awesome App
info.app.description=Customer Relationship Management API
info.app.version=@project.version@

A query to /actuator/info might then return something like this:

{
  "app": {
    "name": "My Awesome App",
    "description": "Customer Relationship Management API",
    "version": "1.2.1-SNAPSHOT"
  },
  "git": {
    "commit": {
      "id": "a1b2c3d",
      "time": "2023-10-27T10:30:00Z"
    }
  }
}

The /metrics endpoint, by contrast, gives you access to a huge amount of runtime data. You can inspect everything from JVM memory usage (jvm.memory.used) to HTTP server request latencies (http.server.requests). For instance, to check the current heap memory usage, you would simply query /actuator/metrics/jvm.memory.used. The response provides the specific value and metadata:

{
  "name": "jvm.memory.used",
  "description": "The amount of used memory",
  "baseUnit": "bytes",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 1.834592E8
    }
  ],
  "availableTags": [
    {
      "tag": "area",
      "values": [
        "heap",
        "nonheap"
      ]
    },
    {
      "tag": "id",
      "values": [
        "G1 Survivor Space",
        "G1 Old Gen",
        "G1 Eden Space",
        "Metaspace",
        "CodeHeap 'profiled nmethods'",
        "Compressed Class Space",
        "CodeHeap 'non-nmethods'",
        "CodeHeap 'non-profiled nmethods'"
      ]
    }
  ]
}

Practical Insight: By actively monitoring specific metrics like jvm.memory.used and system.cpu.usage, development teams can proactively spot memory leaks or performance bottlenecks long before they trigger a system-wide failure.

Dynamic Logging and Security

For live debugging, the /loggers endpoint is one of the most powerful tools in the Actuator toolkit. It lets you view and dynamically change the log levels for your application's packages without needing a restart or a new deployment. Imagine you're hunting down a subtle bug in production that only appears intermittently.

Instead of redeploying with more verbose logging, you can send a simple POST request to /actuator/loggers/com.example.yourpackage with a JSON payload specifying the new log level. Using a tool like curl:

curl -i -X POST -H "Content-Type: application/json" 
-d '{"configuredLevel": "DEBUG"}' 
http://localhost:8080/actuator/loggers/com.example.yourpackage

This single command immediately cranks up the logging for that specific package, helping you capture the data needed to diagnose the problem. Once you're done, you can set it back to INFO just as easily. A capability like this can turn a multi-hour debugging nightmare into a quick fix. You can learn more about optimising your development pipelines by reading our guide on using Git for CI/CD.

However, this level of visibility brings a clear security responsibility. Threat data shows over 2,000 IP scans targeted Actuator endpoints in the past 90 days, with 1,582 of those focused on /health. This highlights why security is non-negotiable, a fact demonstrated when firms using Regulus saw zero breaches after fixing a recent vulnerability. You can discover more insights about these emerging threats to Spring Boot applications on CSO Online.

How to Configure and Customise Actuator Endpoints

Getting the Spring Boot Actuator up and running is just a matter of adding a single dependency to your project's build file. This one addition pulls in all the core functionality needed to start monitoring your application right away.

For a Maven project, add this dependency to your pom.xml:

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

If you're using Gradle, the equivalent line goes into your build.gradle file:

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

Once that dependency is in place, your application is now instrumented with Actuator. However, Spring Boot takes a security-first approach and, by default, only exposes a minimal set of endpoints over the web (like /health). To unlock Actuator’s full potential, you need to explicitly configure which endpoints are made visible.

Exposing and Controlling Endpoints

You can manage which endpoints are exposed through a few simple properties in your application.yml file. This centralised configuration makes it easy to control exactly who sees your operational data.

For a development environment, you might want to expose everything. A wildcard makes this simple:

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

This setting immediately makes endpoints like /metrics, /env, and /loggers accessible. For a production system, however, this is a dangerous practice. It’s a critical security measure to hide any endpoints that could leak sensitive information.

Security First: Never expose all endpoints in a production environment. Endpoints like /env and /heapdump can leak sensitive configuration details and credentials, creating a significant security vulnerability.

A much safer production strategy is to explicitly include only the endpoints you need. For example, to expose only the /health and /info endpoints, your configuration would look like this:

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

Customising the Base Path

For better organisation or to avoid clashing with your application's existing URLs, you can also change the base path for all Actuator endpoints. By default, they are served from /actuator.

To change this to something more descriptive, like /manage, you just need to add one more property:

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

With this change, the health endpoint is now found at /manage/health instead of /actuator/health. These small customisations help you build a much cleaner and more secure API structure. Taking deliberate control of your endpoints is a key step in building a maintainable and production-ready Spring Boot Actuator setup.

Integrating Actuator with Prometheus for Advanced Monitoring

While the built-in Spring Boot Actuator endpoints give you a great real-time snapshot, their true value is unlocked when you feed that data into a proper monitoring system. This is where Micrometer, the metrics engine running under the hood of Actuator, really shines. Think of it as a universal adaptor, letting your application talk to a whole host of monitoring tools, with Prometheus being one of the most popular choices.

The whole setup process is surprisingly straightforward. It boils down to three main steps: adding the right library, telling Actuator what data you want to share, and then making sure it's all locked down.

Setting Up the Prometheus Integration

Getting started is as simple as adding the micrometer-registry-prometheus dependency to your project. This one little addition works its magic behind the scenes, automatically setting up a new endpoint: /actuator/prometheus. This endpoint serves up all your application's metrics in a format that Prometheus is built to understand and collect.

Of course, you still need to tell Actuator that it's okay to show this endpoint to the world. A quick addition to your application.yml is all it takes.

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

With that, your application is ready. The final piece of the puzzle is to tell your Prometheus server where to find this firehose of data. You just need to add a new scrape configuration to your prometheus.yml file, pointing it directly at your application's new metrics endpoint.

scrape_configs:
  - job_name: 'spring-app'
    metrics_path: '/actuator/prometheus'
    scrape_interval: 15s
    static_configs:
      - targets: ['your-application-host:8080']

Once this is wired up, Prometheus will start polling your /actuator/prometheus endpoint every few seconds. It will gather and store this continuous stream of data, giving you a powerful historical record for analysis, dashboarding, and alerting.

Creating and Visualising Custom Metrics

The standard metrics are great, but the real power comes from tracking things that are specific to your business. Let's say you want to keep an eye on how many orders are being placed in your e-commerce app. You can easily create a custom counter using Micrometer's MeterRegistry.

@Service
public class OrderService {
    private final Counter ordersPlacedCounter;

    public OrderService(MeterRegistry registry) {
        this.ordersPlacedCounter = Counter.builder("orders_placed_total")
            .description("Total number of orders placed.")
            .register(registry);
    }

    public void placeOrder() {
        // ... order processing logic ...
        this.ordersPlacedCounter.increment();
    }
}

Now, your custom orders_placed_total metric will automatically show up in the /actuator/prometheus output. The final step is bringing it to life on a dashboard. Using a tool like Grafana, you can connect to Prometheus as a data source and build out your visualisations. A simple query like rate(orders_placed_total[5m]) is all you need to create a graph showing the real-time rate of orders coming in.

Spring Boot Actuator has seen massive adoption across Europe's software manufacturing scene. Code analysis shows that line coverage has hit 93% in actuator-autoconfigure modules, which allows for smooth integration with Micrometer for over 17 different monitoring systems. Tools like Prometheus and Grafana are now used by 65% of firms to support their vulnerability management workflows. You can dive into the full research on these Spring Boot findings at TU Delft's software engineering portal.

As your applications and monitoring needs grow, managing this infrastructure can get complicated. For a deeper look at what's required, you can check out our guide on logging and monitoring requirements for compliance. For those dealing with large-scale deployments, it's also worth exploring more advanced architectures like scaling monitoring with Thanos.

Securing Your Actuator Endpoints in Production

Exposing management endpoints in a production environment is a classic case of risk versus reward. On one hand, the Spring Boot Actuator gives you incredible operational insight. On the other, it can create a massive security hole if you’re not careful.

Leaving sensitive endpoints like /env or /heapdump open to the public is a critical vulnerability. It’s like leaving the keys to your server room hanging on the front door—attackers can walk right in and grab credentials, system properties, and even full memory snapshots.

The first rule of Actuator security is simple: never expose all endpoints. Even a seemingly harmless endpoint can be weaponised. We’ve seen real-world cases where attackers have exploited misconfigurations in reverse proxies to bypass security checks and access Actuator endpoints, leading to major information leaks and even administrative takeovers.

Securing Endpoints with Spring Security

The most robust way to protect your endpoints is to integrate them with Spring Security. This lets you demand proper authentication and authorise access based on specific roles, ensuring only your operations team or other privileged users can see what’s going on under the hood.

First, add the Spring Security dependency to your project. From there, you can define a security configuration that locks down the actuator’s path. The example below ensures that any user trying to access an Actuator endpoint must have the ACTUATOR_ADMIN role.

@Configuration
public class ActuatorSecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.securityMatcher("/actuator/**")
            .authorizeHttpRequests(authorize -> authorize
                .anyRequest().hasRole("ACTUATOR_ADMIN")
            )
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

This simple configuration tells Spring to intercept any request to /actuator/** and check for the right credentials. An unauthorised attempt gets a blunt 401 Unauthorized response, effectively slamming the door on any prying eyes. For a deeper dive on building security into your process, have a look at our guide on the secure software development life cycle.

Architectural Security Strategies

Beyond just writing secure code, you should also think about defence-in-depth from an architectural standpoint.

A powerful strategy is to expose the management endpoints on a completely separate port from your main application traffic. This makes it much easier to apply strict firewall rules that block public access to the management interface entirely.

You can do this with a single property in your application.yml:

management:
  server:
    port: 9091

This one line completely isolates the Actuator, making it accessible only from within a private network or through a secure bastion host. By combining strong role-based access control with smart network isolation, you get to use the full power of Spring Boot Actuator without putting your production environment at risk.

Using Actuator for IoT and Cyber Resilience

While most developers think of Spring Boot Actuator in the context of web applications, it's also a powerful tool for monitoring connected hardware and Internet of Things (IoT) devices. Its capabilities go far beyond typical server-side monitoring, offering functions that are essential for resilience and, increasingly, regulatory compliance.

As regulations like the EU's Cyber Resilience Act (CRA) come into effect, manufacturers have to provide solid evidence of security and post-market surveillance. Actuator provides a direct, hands-on way to meet these obligations.

Monitoring Devices in the Field

Imagine you have thousands of smart meters or industrial sensors deployed across a city. How do you know they are all running correctly? The /health endpoint becomes your lifeline, allowing a central system to poll each device and check its status. If a device reports DOWN, you can automatically trigger a maintenance alert and ensure service reliability.

For example, a custom health check could verify a sensor's connection to a back-end service:

@Component
public class ExternalSensorHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        if (isSensorConnected()) {
            return Health.up().withDetail("sensor_api", "available").build();
        }
        return Health.down().withDetail("sensor_api", "unavailable").build();
    }

    private boolean isSensorConnected() {
        // Logic to check connection to the sensor's API
        return true; // or false
    }
}

When this is included, a call to /actuator/health provides detailed status, such as: {"status":"UP","components":{"externalSensor":{"status":"UP","details":{"sensor_api":"available"}}}}.

It's the same idea for remote checks using the /info endpoint. You can configure it to expose the device's current firmware version, giving you an instant way to confirm which units have received a critical security patch and which are still vulnerable.

Gathering Compliance Evidence

The CRA mandates that products with digital elements are secure throughout their lifecycle. Actuator's endpoints provide tangible proof of compliance, turning what's often seen as a simple developer tool into a strategic asset for your technical documentation and security assessments.

• /metrics for Performance: On a resource-constrained IoT device, tracking CPU and memory usage is critical. Querying /actuator/metrics/system.cpu.usage helps demonstrate that the device operates within safe performance limits, a key aspect of security and stability.
• /health for Status: Using custom health indicators to check sensor connections or the state of internal hardware components gives you auditable proof of device integrity.
• /loggers for Audits: The ability to remotely change log levels on a device is invaluable. During a security incident investigation, you can dial up the logging to gather detailed diagnostic data, directly fulfilling your post-market surveillance duties.

This isn't just a theoretical benefit; it's already happening. In the European manufacturing sector, Spring Boot Actuator has become a cornerstone for companies working toward CRA compliance. A recent survey showed that over 68% of Java-based applications in automotive and industrial IoT deployments now use Actuator for real-time health checks. You can find more on these trends from the International Federation of Robotics.

By embedding Actuator into IoT products, you build in the observability needed for both operational excellence and regulatory confidence. It provides a standardised, auditable trail that shows a product is being actively monitored and maintained throughout its lifecycle.

Of course, securing these endpoints is paramount, especially in a distributed ecosystem of connected devices. Our guide on endpoint protection services offers further strategies for safeguarding your device communications.

Frequently Asked Questions About Spring Boot Actuator

To help you get the most out of Spring Boot Actuator, let’s tackle a few common questions that come up when developers first start using it.

What Is the Difference Between the Health and Info Endpoints?

The /health endpoint is designed specifically for automated systems. It gives a straightforward, machine-readable status, like UP or DOWN, which monitoring tools use to check if your application is alive and well.

Think of it as a simple pulse check. A response of {"status":"UP"} is all a load balancer needs to keep sending traffic.

The /info endpoint, on the other hand, is for humans. It’s the right place for static, descriptive details like the build version, a project description, or even the Git commit ID. Use /health for automated alerts and /info when you need to manually check application metadata.

Can I Create My Own Custom Health Indicators?

Yes, absolutely—and this is one of its most powerful features. You can build a custom health indicator by implementing the HealthIndicator interface and registering your class as a Spring bean.

This is perfect for checking the status of critical dependencies that are specific to your application, such as a database connection, a message queue, or a vital third-party API. Here is a practical example for checking a third-party service:

@Component
public class MyApiServiceHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        try {
            // Simulate calling an external API
            int responseCode = callExternalApi();
            if (responseCode == 200) {
                return Health.up().withDetail("api_status", "reachable").build();
            } else {
                return Health.down().withDetail("api_status", "unreachable")
                                     .withDetail("http_status", responseCode).build();
            }
        } catch (Exception e) {
            return Health.down(e).build();
        }
    }

    private int callExternalApi() {
        // In a real app, you would use RestTemplate or WebClient here
        return 200;
    }
}

If your custom check fails, it will correctly report a DOWN status to the main /health endpoint. This allows you to integrate application-specific health checks directly into your overall monitoring strategy, providing a more accurate picture of your system's true status.

Is It Safe to Expose All Actuator Endpoints in Production?

No, doing so is highly unsafe and creates a major security risk. You should never expose all endpoints in a production environment.

Endpoints like /env, /heapdump, or /loggers can leak incredibly sensitive information, including configuration data, credentials, and internal memory details. The best practice is to expose only the essential endpoints (like /health) and lock everything down with Spring Security.

---

Are you preparing your digital products for EU regulatory deadlines? Regulus provides a unified platform to assess Cyber Resilience Act applicability, classify your products, and generate a tailored compliance roadmap. Gain clarity and confidently place your products on the European market by visiting https://goregulus.com.