In this tutorial, we will learn about spring actuators. Also, we will see how it helps to monitor and manage your application seamlessly.
Overview
The actuator is a monitoring function provided by the Spring Boot framework. The actuator works by exposing endpoints, that can be used to monitor the internal conditions of the Spring Boot application, such as automatic configuration, spring beans information, health metrics, obtaining the current properties property values, threads information etc.
In the following sections, you will learn in detail how to enable the Spring Boot actuator in your application.
Preparation:
- JDK 1.8
- Intellij Idea for IDE
- Maven
- SpringBoot Application
- Lombok plugin
Creating a Basic Spring Boot Application
Firstly, we create a simple Spring Boot web application. Here, you can use the Spring Initializr page to create an initial project template.
Once you import the project into IDE, the final project structure will look like this:
Include Dependencies
To include Spring Boot Actuator inside a REST API, we just have to add following maven starter dependency:
<dependency> <groupID>org.springframework.boot</groupID> <artifactID>spring-boot-starter-actuator</artifactID> </dependency>
<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.5.0</version> <relativePath/> </parent> <groupId>com.appsdeveloperblog</groupId> <artifactId>spring-boot-actuator</artifactId> <version>0.0.1-SNAPSHOT</version> <packaging>jar</packaging> <name>springboot-actuator-example</name> <description>Spring boot actuator tutorial</description> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> <java.version>1.8</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>
Spring Boot Actuator
Once Maven dependency for the actuator is included, spring actuators are ready to consume. By default, the following two actuators are enabled at runtime and the remaining are disabled due to security reasons.
- /actuator/health
- /actuator/info
Here, /actuator/health endpoint allows us to test whether the Microservice is running or not. It is widely used in monitoring running instances of microservices. By regularly checking this endpoint, you can expose the live status of your Microservices application. whereas, /actuator/info allows us to display the application-related info.
Let’s understand both of these endpoints in action.
First, we will compile and run our application using a standard process with the below command or directly executing the IDE run command.
mvn clean install mvn spring-boot:run
once the application starts successfully. Next, you run the following URL in the browser,
http://localhost:8080/actuator/health
As you can see, the application status is displayed as “UP” which means the app is running successfully.
Similarly for endpoint /actuator/info. We need to create application info data that will be exposed via this endpoint.
First, we will create file name application.properties inside /resources directory.
The complete source code for “application.properties” file is as follow:
info.application.name=AppsDeveloper Blog demo info.application.description=A Demo for Spring Boot Actuator info.application.author.name= Sharad Dixit info.application.author.bio= Software Developer
After compiling and re-runing our application again. If we navigate to the following actuator URL in the browser:
http://localhost:8080/actuator/info
the browser will expose the application info as below:
As you can see, this actuator can provide application information for any microservice.
Enabling Hidden Endpoints
In addition to the above two actuators, spring allows us to activate another series of actuators that are already predefined. In order to activate the rest of the actuators endpoints, we have to go to our application.properties file and modify the following property and set it with the asterisk value as below:
management.endpoints.web.exposure.include = *
This property will expose all pre-defined lists of actuators. Although, this is not a good idea when your microservice is in production. Instead, we should choose specific endpoints to display.
Here, several methods are possible, but the easiest is to include only those that interest us in the property as below:
management.endpoints.web.exposure.include=health,info,metrics
With this property, only these endpoints are exposed.
Now if we navigate to the following URL
http://localhost:8080/actuator/
Spring will display the list of exposed actuators provided by spring based on the property set. For example, if the property “management.endpoints.web.exposure.include” is marked as *.
Below is the basic description of the most common endpoint actuator:
ID | explanation | Initial Value |
---|---|---|
autoconfig | Shows all auto-config definitions | true |
beans | Shows all beans managed by Spring. | true |
dump | Provides thread dump details for each thread | true |
env | Shows Spring’s ConfigurableEnvironment values. | true |
health | Displays application health. | false |
info | Shows application information. | false |
loggers | Shows the log information used in the application. | true |
mappings | The @RequestMapping definition shows the values made. | true |
trace | Lists the 100 most recently used HTTP requests. | true
|
You can read in full detail about each endpoint in the official documentation here.
Custom Endpoints
It is also possible to create custom endpoints based on individual requests. For example, if we want to create a dedicated endpoint into our application that shows the “Change-Log” for our application on each release. This can be achieved easily in Spring Boot Version 2 using @Endpoint
annotation.
Next, we will create a class called “CustomActuator.java” in our package which will be annotated with @component annotation to create a Spring-managed component. In this class, we will create a custom endpoint using @Endpoint annotation. Later via @ReadOperation (maps to HTTP GET), we read the response.
The complete code for CustomActuator.java is as follow:
package com.appsdeveloperblog; import org.springframework.boot.actuate.endpoint.annotation.Endpoint; import org.springframework.boot.actuate.endpoint.annotation.ReadOperation; import org.springframework.stereotype.Component; @Component @Endpoint(id="change-logs") public class CustomActuator { String changelog = "** version 2.0 ** \n\n" + "* Improved performance \n" + "* removed bug fix with local-id \n" + "* Added support of SAML authentication \n"; @ReadOperation public String changeLogs() { return changelog; } }
now if we run our application and navigate to our custom endpoint
http://localhost:8080/actuator/change-logs
After that, it will display me my change log details
Conclusion
In this tutorial, we learned how to use Spring Boot Actuator to check the status and metrics of your system. This helps developers to monitor the internals of Microservices. For example, health matrix, environment variables, performance, threads information etc. in the simplest way.