Spring Boot Actuator: Monitor Your Spring Boot Project

Spring Boot provides plenty of features to assist us in monitoring and managing our application. Spring Boot Actuator is a sub-project of the Spring Boot that helps us in monitoring and managing our Spring Boot application. It provides several features to monitor different modules of the project such as health, metrics, resources, etc.

In Spring Boot Actuator, we are allowed to choose to manage and monitor our application using the HTTP endpoints or JMX. It will auto-enable features such as Auditing, Health, and Metrix to our application.

In a nutshell, the Spring Boot actuator provides a production-ready application, which can be managed and monitored using its features.

In this article on learning Spring Boot, we will discuss Spring Boot actuator using starter actuator dependency, Spring Boot actuator features with several examples.

In this section, we have included the following topics:

• What is Spring Boot Actuator
• Spring Boot Starter Actuator
• Features of Spring Boot Actuator
• How to Enable Spring Boot Actuator
• Spring Boot Actuator Endpoints
• How to Enable Actuator Endpoints
• How to Expose Actuator Endpoints
• Spring Boot Actuator Properties
• Spring Boot Actuator Example
• Health Endpoints (Spring Boot Health Check)

What is Spring Boot Actuator

Spring Boot Actuator is one of the most fascinating features of Spring Boot for providing production-ready applications. It is useful for monitoring an application. The key advantage of Spring Boot Actuator is that we are not required to put the lots of boilerplate code to monitor application, instead, we just need to add a spring-boot-starter-actuator dependency in our pom.xml file.

According to Spring’s Official Definition:

“An actuator is a manufacturing term that refers to a mechanical device for moving or controlling something. Actuators can generate a large amount of motion from a small change.”

Spring Boot Starter Actuator

Spring Boot Starter Actuator is a starter dependecy for Actuator. The schema for the adding the spring-boot-starter-actuator dependency is as follows:

For Maven Project:

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

For Gradle project:

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

The above schema will be added in the project configuration file ( pom.xml for maven).

Features of Spring Boot Starter Actuator

The following are some key features offered by Spring Boot Starter Actuator:

• Health check: It provides a health check endpoint to check the status of your running application.
• Monitoring and Management over HTTP/JMX: The Spring Boot actuator supports two endpoints; HTTP and JMX (Java Management Extensions). It provides a standard mechanism to monitor and manage the applications.
• Logger: The logger is useful for viewing and updating the logs level.
• Metrics: The Actuator provides built-in support for dependency management and auto-configuration for Micrometer, which is useful for monitoring several systems.
• Auditing: When we integrate the Spring Security in our project then the Actuator plays a vital role as an Audit framework that publishes events (by default, “authentication success”, “failure” and “access denied” exceptions). The Auditing feature will be very useful for reporting and for implementing a lock-out policy based on authentication failures.
• Http Tracing: It provides an HTTP Tracing. It can be enabled by providing a bean of type HttpTraceRepository in your application’s configuration.
• Process Monitoring

How to Enable Spring Boot Actuator

To enable the Spring Boot Actuator, add the spring-boot-starter-actuator dependency in our pom.xml file under the <dependencies> tag. The schema of spring-boot-starter-actuator is as follows:

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

Spring Boot Actuator Endpoints

The Actuator endpoints allow us to monitor and interact with our application. The Spring Boot facilitates with several endpoints and also allows to create customized endpoints. For example, to monitor the health of the project, we can use a health endpoint.

We can enable or disable and expose each individual endpoint over HTTP or JMX. An endpoint is available when it is enabled and exposed. We can only auto-configure the built-in endpoints when they are available.

Most of the applications choose exposure using HTTP, where the ID of the endpoint with a prefix /actuator is mapped to a URL. For example, the default mapping for the health endpoint is /actuator/health.

Spring Boot Starter Actuator holds the following endpoints:

ID	Description
auditevents	The auditevents endpoint is used to expose the audit events information for the current application. It requires an AuditEventRepository bean.
beans	The beans endpoint is used to display a complete list of all the Spring beans in our application.
caches	The caches endpoint is used to exposes available caches.
conditions	The conditions endpoint is used to display the conditions that were evaluated on configuration and auto-configuration classes. Further, it displays the reasons why they did or did not match.
configprops	The configprops endpointis used to display a collated list of all @ConfigurationProperties.
env	The env endpoint is used to expose the properties from Spring’s ConfigurableEnvironment.
flyway	The flyway endpoint is used to display any Flyway database migrations that have been applied. It requires one or more Flyway beans.
health	The health endpoint is used to display the application health information.
httptrace	The httptrace endpoint is used to display the HTTP trace information (by default, the last 100 HTTP request-response exchanges). It requires an HttpTraceRepository bean.
info	The info endpoint is used to display the arbitrary application info.
integrationgraph	The integrationgraph is used to display the Spring Integration graph. It requires a dependency on spring-integration-core.
loggers	The loggers endpoint is used to display and modify the configuration of loggers in the application.
liquibase	The liquibase endpoint is used to display any Liquibase database migrations that have been applied. It requires one or more Liquibase beans.
metrics	The metrics endpoint is used to display ‘metrics’ information for the current application.
mappings	The mappings endpoint is used to display a collated list of all @RequestMapping paths.
scheduledtasks	The scheduledtasks endpoint is used to display the scheduled tasks in our application.
sessions	The sessions endpoint is used to allow retrieval and deletion of user sessions from a Spring Session-backed session store. It requires a Servlet-based web application using Spring Session.
shutdown	The shutdown endpoint is used to let the application shutdown gracefully. It is disabled by default.
startup	The startup endpoint is used to display the startup steps data collected by the ApplicationStartup. It requires the SpringApplication to be configured with a BufferingApplicationStartup.
threaddump	The threaddump endpoint is used to perform a thread dump.

There are some additional endpoints provided by Actuator for the web applications such as Spring MVC, Spring WebFlux, or Jersey. The following are some additional endpoints that is useful for the web applications:

ID	Description
heapdump	The heapdump endpoint is used to return an hprof heap dump file.
jolokia	The jolokia endpoint is used to exposes JMX beans over HTTP (when Jolokia is on the classpath, not available for WebFlux). It requires a dependency on jolokia-core.
logfile	The logfile endpoint is used to return the contents of the logfile (if logging.file.name or logging.file.path properties have been set). It supports the use of the HTTP Range header to retrieve part of the log file’s content.
prometheus	The prometheus endpoint is used to expose a metrics in a format that can be scraped by a Prometheus server. It requires a dependency on micrometer-registry-prometheus.

How to Enable Actuator Endpoints

By default, all the endpoints are enabled, except for the shutdown endpoint. We can confirm the enablement of an endpoint by using its management.endpoint.<id>.enabled property. Consider the below configuration for enabling the shutdown endpoint:

application.properties:

management.endpoint.shutdown.enabled=true

application.yaml:

management:
  endpoint:
    shutdown:
      enabled: true

To ensure the enablement of the endpoint to be opt-in rather than opt-out, we must set the management.endpoints,enabled-by-default property to false and the individual endpoints enabled properties to opt back in.

For example, to enable the info endpoint and disable all other endpoints, execute the below code:

application.properties:

management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true

application.yaml:

management:
  endpoints:
    enabled-by-default: false
  endpoint:
    info:
      enabled: true

Note: When we disable endpoints, they will be entirely removed from the application context. If you want to change only the technologies over which an endpoint is going to be exposed, you should use the include and exclude properties.

How to Expose Actuator Endpoints

We should be very careful while exposing the endpoints since they contain very sensible informations. Consider the below table which contains the default exposure for the built-in endpoints:

ID	JMX	Web
auditevents	Yes	No
beans	Yes	No
caches	Yes	No
conditions	Yes	No
configprops	Yes	No
env	Yes	No
flyway	Yes	No
health	Yes	Yes
heapdump	N/A	No
httptrace	Yes	No
info	Yes	Yes
integrationgraph	Yes	No
jolokia	N/A	No
logfile	N/A	No
loggers	Yes	No
liquibase	Yes	No
metrics	Yes	No
mappings	Yes	No
prometheus	N/A	No
scheduledtasks	Yes	No
sessions	Yes	No
shutdown	Yes	No
startup	Yes	No
threaddump	Yes	No

To change the exposure of a specific endpoint, use the following include and exclude properties:

Property	Default
management.endpoints.jmx.exposure.exclude
management.endpoints.jmx.exposure.include	*
management.endpoints.web.exposure.exclude
management.endpoints.web.exposure.include	info, health

The include property displays the endpoint’s Id that are going to be exposed. The exclude property displays the endpoint’s id that should not be exposed. The exclude property has precedence over the include property. Both of these properties can be configured with a list of Ids.

Consider the below example that is stop exposing all endpoints over JMX and only expose the health and info endpoints:

application.properties:

management.endpoints.jmx.exposure.include=health,info

application.yaml:

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

The symbol “*” can be used to select all endpoints. For example, if you want to expose everything over HTTP except the env and beans endpoints, the following code will be executed:

application.properties:

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans

application.yaml:

management:
  endpoints:
    web:
      exposure:
        include: "*"
        exclude: "env,beans"

Actuator Properties

Spring Boot Actuator allows security for all of its endpoints by using a form-based authentication process that gives a user id as the user and a random password. We can customize basicauth security to the endpoints to access the actuator-restricted endpoints. In order to do so, we have to override the configuration by management.security.roles property.

Consider the below configuration code:

management.security.enabled=true  
management.security.roles=ADMIN  
security.basic.enabled=true  
security.user.name=admin  
security.user.passowrd=admin 

Let’s create an actuator project to understand the endpoints:

Actuator Example

Follow the below steps to create a Spring Boot Actuator project:

Step1: Open Spring Initializr

We are creating the project using the Spring Initializr which we found the easiest way to generate a Spring Boot project. To create the project using Spring Iniatializr, navigate to https://start.spring.io/.

Step2: Provide the Project Details

Now, provide the project details such as group id and artifact id, etc. We are using the com.javasterling as group id and actuator-demo as artifact id and maven as our build tool.

Step3: Add Dependencies

Add the following three dependencies:

1. Spring Web
2. Spring Boot Actuator
3. Rest Repository Hall Explorer (Spring Data Rest Hall Browser)

Now, our project will look like as follows:

Step4: Generate Project

Now, select click on the Generate option to create this project. It will download a compressed file.

Step5: Extract Project

To import in our IDE we have to extract this project.

Extract this project to your Spring Boot workspace.

Step6: Import Project Into IDE

Import it to your favorite IDE. We are using the STS IDE, so to import it into Spring Tool Suite, navigate to File-> Open project from File System and navigate to your workspace and select this project. Click Finish to import it into our IDE.

It will take some time to import the project files.

After importing it, we can see our project directory will look like as follows:

See How to Import a project in Eclipse and Spring Tool Suite.

Step7: Create a Controller Class

Now, create a controller class under the package src/main/java/ com.javasterling.actuatordemo with the name TestRestController. To create a class file right-click on the package and navigate to New->Class and provide the class name:

Click Finish to continue.

Add the following code in our TestRestController.java file.

TestRestController.java:

package com.javasterling.actuatordemo;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class TestRestController {
	@GetMapping("/hello")  
	public String hello()   
	{  
	return "Hello User!";  
	}  
}

Step8: Define Properties

We can define the properties in application.properties file which can be found under the src/main/resources folder. For this project we are disabling the security feature of the actuator by as follows:

application.properties:

management.security.enabled=false

Now, our actuator project is ready to run.

Step9: Run the Project

To run the project, right-click on the ActuatorDemoApplication.java file and run it as Java Application.

We can see our project is successfully running:

Step10: Test in on Browser

To test in our browser, open your web browser and type the below address: http://localhost:8080/actuator

It will produce the following result:

{"_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},"info":{"href":"http://localhost:8080/actuator/info","templated":false}}}

Now, our actuator application is successfully executed. We can test different endpoints.

Health Endpoints

The health endpoint displays the application’s health status. The health of a Spring Boot project can be checked using the below URL:

http://localhost:8080/actuator/health

It will display the health status as UP if the application is working properly. Consider the below result:

{"status":"UP"}

if there is an issue with the application health it will result as down. There may be several causes such as database connectivity, lack of disk space, etc., that may down your Spring Boot application.