Spring Boot Actuator Rest Endpoints Example

By Dhiraj Ray, 10 February,2017  

Hello friends, this post is continuation to Spring Boot Actuator Complete Tutorial Guide. I strongly encourage you to go through it before continuing here. In this post, we will be discussing about the different REST endpoints of spring boot actuator with examples. We will be creating an example spring boot app and integrate actuator in it. The example will demonstrate the different actuator endpoints, customizing endpoints, securing endpoints and also creating custom endpoints.

Background

Spring boot actuator is a sub-project of spring boot. Once spring boot actuator is integrated in your spring boot app, there are around 16 default REST endpoints you get as mentioned below to monitor and manage your application. By using these default endpoints you can monitor your application health, check the beans configured, monitor your application properties and many more. Also you can restrict the endpoints access to certain role by integrating with spring security. You can customize default endpoints and even create your own custom endpoints to monitor your application.

Different Actuator Endpoints

Once above maven dependency is included in the pom file, you can get following 16 implicit endpoints. Some of them are sensitive and some are not. In the following list the only endpoints which are not sensitive are health and info.

1. actuator : It provides a hypermedia-based discovery page for the other endpoints. It is required to have Spring HATEOS on the classpath to enable it. By default it is sensitive and hence requires username/password for access or may be disabled if web security is not enabled.

2. auditevents: It exposes audit events information.

3. autoconfig: It displays an auto-configuration report showing all auto-configuration candidates.

4. beans: It displays complete beans configured in the app.

5. configprops: It displays a collated list of all @ConfigurationProperties.

6. dump: It performs a thread dump.

7. env: It exposes properties from Spring ConfigurableEnvironment.

8. flyway: It shows any Flyway database migrations that have been applied.

9. health: It shows application health information (when the application is secure, a simple ‘status’ when accessed over an unauthenticated connection or full message details when authenticated).

10. info: It displays arbitrary application info.

11. loggers: It shows and modifies the configuration of loggers in the application.

12. liquibase: It shows any Liquibase database migrations that have been applied.

13. metrics: It shows metrics information for the current application.

14. mappings: It displays a collated list of all @RequestMapping paths.

15. shutdown: It allows the application to be gracefully shutdown (not enabled by default).

16. trace: It displays trace information (by default the last 100 HTTP requests).

If you are also using spring mvc then other 4 additional endpoints such as docs, heapdump, jolokia and logfile can be used

Now let us start building our spring boot app and integrate actuator in it.

Environment Setup

1. JDK 8 2. Spring Boot 4. Intellij Idea/ eclipse 5. Maven

Project Structure

spring-boot-actuator-example-structure

Maven Dependencies

spring-boot-starter-parent: provides useful Maven defaults. It also provides a dependency-management section so that you can omit version tags for existing dependencies.

spring-boot-starter-web: includes all the dependencies required to create a web app. This will avoid lining up different spring common project versions.

spring-boot-starter-tomcat: enable an embedded Apache Tomcat 7 instance, by default. We have overriden this by defining our version. This can be also marked as provided if you wish to deploy the war to any other standalone tomcat.

spring-boot-starter-actuator: Enables spring boot actuator features in spring boot.

pom.xml
<?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 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.devglan</groupId> <artifactId>spring-boot-actuator-endpoints</artifactId> <version>0.1.0-SNAPSHOT</version> <packaging>war</packaging> <properties> <java.version>1.8</java.version> </properties> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>1.5.1.RELEASE</version> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-tomcat</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>

Defining Application class

@SpringBootApplication enables many defaults. It also enables @EnableWebMvc that activates web endpoints.

Application.java
package com.devglan.config; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }

Accessing Non Restricted Actuator Endpoints

With this much configurations, you can start consuming your actuator endpoints. As there are only 2 non-restricted actuator endpoints, you should be able to monitor your application with these 2 endpoints. Other restricted endpoints will be disabled at this point as there is no spring security enabled yet. You can also configure it manually o disable it. We will talk about enabling it in next section.

Now, run Application.java as a java application and you can see the logs as below which shows all the endpoints info exposed by spring boot actuator by default.

spring-boot-actuator-log

Once the application is deployed, make a http call to localhost:8080/health and you can see below response about the health status of your app.

{ status: "UP" }

Enabling Security to Spring Boot Actuator Endpoints

Add following maven dependencies in you pom.xml first.

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

Make following entries in your application.properties file. It will enable the restricted actuator endpoints.

management.security.enabled=true security.basic.enabled=true

To access the actuator restricted endpoints, you require to have ACTUATOR role and hence let us configure spring boot security to have ACTUATOR role with username/password as act/act. If you are unknown to spring boot security then I recommend to follow Spring Boot Security Example first.

SpringSecurityConfig.java
package com.devglan.config; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter; @EnableWebSecurity public class SpringSecurityConfig extends WebSecurityConfigurerAdapter { @Autowired public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception { auth.inMemoryAuthentication().withUser("admin").password("admin").roles("ADMIN"); auth.inMemoryAuthentication().withUser("act").password("act").roles("ACTUATOR"); } }

Now the different restricted actuator endpoints are enabled and ready to be consumed. Hit the url http://localhost:8080/beans and you will be served with a Json file named beans which will contain all the bean definitions of your spring boot application.

Similarly, you can access other restricted endpoints like /metrics and get your metrics file having content similar to following.

{ "mem": 316656, "mem.free": 169495, "processors": 4, "instance.uptime": 1449726, "uptime": 1463662, "systemload.average": -1.0, "heap.committed": 263168, "heap.init": 131072, "heap.used": 93672, "heap": 1846272, "nonheap.committed": 54400, ........ }

To secure actuator REST endpoints by AuthenticationManagerBuilder visit Securing Spring Boot Actuator Endpoints with Spring Security

Customizing Actuator Endpoints

Spring boot provides customizing endpoints by using spring properties. Simply, mention the properties you want to customize in your application.properties. You can customize an endpoint in 3 ways. You can <enable or disable an endpoint, customize its sensitivity and also its id.

Let us customize our /metrics endpoint to be available at /mymetrics.You can also customize the sensitive property and even can shutdown the /metrics endpoint as follow.

endpoints.metrics.id=mymetrics endpoints.metrics.sensitive=false endpoints.shutdown.enabled=true

Now, the same metrics is available at /mymetrics endpoint instead of actuator default /metrics as customized by us.

spring-boot-actuator-customization

Creating Custom Endpoints

Spring also allows to define your own actuator endpoints. To do this, you just have to implement the interface Endpoint and override its methods and you are done. Let us define our custom actuator endpoint at /showendpoints which will show all the endpoints.

ListEndPoints.java
import org.springframework.boot.actuate.endpoint.AbstractEndpoint; import org.springframework.boot.actuate.endpoint.Endpoint; import org.springframework.stereotype.Component; import java.util.List; @Component public class ListEndPoints extends AbstractEndpoint> { private List endpoints; public ListEndPoints(List endpoints) { super("showendpoints"); this.endpoints = endpoints; } @Override public List invoke() { return this.endpoints; } }
Now hit the url http://localhost:8080/showendpoints and you can expect following result. spring-boot-actuator-custom-endpoint

Conclusion

I hope this article served you that you were looking for. If you have anything that you want to add or share then please share it below in the comment section.

Download the source

References

Spring Actuator Service

Suggest more topics in suggestion section or write your own article and share with your colleagues.

Is this page helpful to you? Please give us your feedback below. We would love to hear your thoughts on these articles, it will help us improve further our learning process.

Further Reading: