Spring Boot Actuator
Table of Contents
- What Is An Actuator?
- How to Enable an Actuator?
- Endpoints
- Custom Metric Data
- Create A New Endpoint
- A New Endpoint To List All Endpoints
- Actuator Example application
- Summary
1. What Is Spring Boot Actuator?
2. How To Enable Spring Boot Actuator?
2.1 In Maven Project
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency>
2.2 In Gradle Project
dependencies { compile("org.springframework.boot:spring-boot-starter-actuator") }
3. Endpoints
- /actuator- Provides a hypermedia-based “discovery page” for the other endpoints. Requires Spring HATEOAS to be on the classpath. Sensitive by Default.
- /autoconfig- Displays an auto-configuration report showing all auto-configuration candidates and the reason why they ‘were’ or ‘were not’ applied. Sensitive by Default.
- /beans- Displays a complete list of all the Spring beans in your application. Sensitive by Default.
- /configprops- This endpoint shows configuration properties used by your application. Sensitive by Default.
- /dump- Performs a thread dump. Sensitive by Default.
- /env- Exposes spring’s properties from the configurations. Sensitive by Default.
- /health – Shows application health information (a simple ‘status’ when accessed over an unauthenticated connection or full message details when authenticated). It is sensitive by default.
- /info – Displays arbitrary application info. Not sensitive by default.
- /metrics – Shows ‘metrics’ information for the current application. It is also sensitive by default.
- /mappings- Displays a list of all @RequestMapping paths. Sensitive by Default.
- /shutdown- This endpoint allows to shutdown the application. This is not enabled by default. Sensitive by Default.
- /trace – Displays trace information (by default the last few HTTP requests). Sensitive by Default.
- /logfile– Provides access to the configured log files (This feature supported since Spring Boot 1.3.0). Sensitive by Default.
- /flyway- This endpoint provides the details of any flyway database migrations have been applied. Sensitive by Default.
- /liquibase- This endpoint provides the details of any liquibase database migrations have been applied. Sensitive by Default.
- id – by which this endpoint will be accessed over HTTP
- enabled – if true then it can be accessed otherwise not
- sensitive – if true then need authorization to show crucial information over HTTP
- management.port=8081 – you can expose those endpoints on port other than the one application is using (8081 here).
- management.address=127.0.0.1 – you can only allow to access by IP address (localhost here).
- management.context-path=/actuator – allows you to have those endpoints grouped under specified context path rather than root, i.e. /actuator/health.
- endpoints.health.enabled=false – allows to enable/disable specified endpoint by name, here /health is disabled.
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> </dependency>
security.basic.enabled=false
security.user.name=admin security.user.password=secret management.security.role=SUPERUSER
management.security.enabled=false
{ "status" : "UP" }
endpoints.health.sensitive=false
- DiskSpaceHealthIndicator
- DataSourceHealthIndicator
- MongoHealthIndicator
- RabbitHealthIndicator
- SolrHealthIndicator
endpoints.health.id=health endpoints.health.sensitive=true endpoints.health.enabled=true
/** * */ package com.dineshonjava.sba; import org.springframework.boot.actuate.health.Health; import org.springframework.boot.actuate.health.HealthIndicator; /** * @author Dinesh.Rajput * */ public class MyAppHealth implements HealthIndicator{ @Override public Health health() { int errorCode = check(); // perform some specific health check if (errorCode != 0) { return Health.down().withDetail("Error Code", errorCode).build(); } return Health.up().build(); } private int check() { // Your logic to check health return 0; } }
{ status: "UP", diskSpace: { status: "UP", total: 240721588224, free: 42078715904, threshold: 10485760 } }
{ endpoints.info.id=info endpoints.info.sensitive=false endpoints.info.enabled=true info.app.name=Spring Boot Actuator Application info.app.description=This is my first Working Spring Actuator Examples info.app.version=0.0.1-SNAPSHOT
{ { app: { version: "0.0.1-SNAPSHOT", description: "This is my first Working Spring Actuator Examples", name: "Spring Boot Actuator Application" } }
{ endpoints.metrics.id=metrics endpoints.metrics.sensitive=true endpoints.metrics.enabled=true
{ { mem: 55470, mem.free: 5398, processors: 4, instance.uptime: 9452, uptime: 14466, systemload.average: -1, heap.committed: 35020, heap.init: 16384, heap.used: 29621, heap: 253440, nonheap.committed: 20800, nonheap.init: 160, nonheap.used: 20451, nonheap: 0, threads.peak: 17, threads.daemon: 14, threads.totalStarted: 20, threads: 16, classes: 6542, classes.loaded: 6542, classes.unloaded: 0, gc.copy.count: 60, gc.copy.time: 232, gc.marksweepcompact.count: 2, gc.marksweepcompact.time: 61, httpsessions.max: -1, httpsessions.active: 0 }
- The total system memory in KB (mem)
- The amount of free memory in KB (mem.free)
- The number of processors (processors)
- The system uptime in milliseconds (uptime)
- The application context uptime in milliseconds (instance.uptime)
- The average system load (systemload.average)
- Heap information in KB (heap, heap.committed, heap.init, heap.used)
- Thread information (threads, thread.peak, thread.daemon)
- Class load information (classes, classes.loaded, classes.unloaded)
- Garbage collection information (gc.xxx.count, gc.xxx.time)
- The number of active connections (datasource.xxx.active)
- The current usage of the connection pool (datasource.xxx.usage).
- The current size of the cache (cache.xxx.size)
- Hit ratio (cache.xxx.hit.ratio)
- Miss ratio (cache.xxx.miss.ratio)
4. Custom Metric Data
/** * */ package com.dineshonjava.sba; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.actuate.metrics.CounterService; import org.springframework.stereotype.Service; /** * @author Dinesh.Rajput * */ @Service public class LoginService { CounterService counterService; @Autowired public LoginService(CounterService counterService) { this.counterService = counterService; doLogin(); } public boolean login(String userName, String password) { boolean success; if (userName.equals("admin") && "secret".equals(password)) { counterService.increment("counter.login.success"); success = true; } else { counterService.increment("counter.login.failure"); success = false; } return success; } private void doLogin() { for(int i=0; i<10; i++){ login("admin", "secret"); } login("admin", "scret"); login("admin", "scret"); } }
...... counter.login.failure: 2, counter.login.success: 10 .... }
5. Create A New Endpoint
/** * */ package com.dineshonjava.sba; import java.util.ArrayList; import java.util.List; import org.springframework.boot.actuate.endpoint.Endpoint; import org.springframework.stereotype.Component; /** * @author Dinesh.Rajput * */ @Component public class MyCustomEndpoint implements Endpoint<List<String>>{ @Override public String getId() { return "myCustomEndpoint"; } @Override public List<String> invoke() { // Custom logic to build the output List<String> list = new ArrayList<String>(); list.add("App message 1"); list.add("App message 2"); list.add("App message 3"); list.add("App message 4"); return list; } @Override public boolean isEnabled() { return true; } @Override public boolean isSensitive() { return true; } }
[ "App message 1", "App message 2", "App message 3", "App message 4" ]
6. A New Endpoint To List All Endpoints
/** * */ package com.dineshonjava.sba; import java.util.List; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.actuate.endpoint.AbstractEndpoint; import org.springframework.boot.actuate.endpoint.Endpoint; import org.springframework.stereotype.Component; /** * @author Dinesh.Rajput * */ @Component @SuppressWarnings("rawtypes") public class MyListEndpoints extends AbstractEndpoint<List<Endpoint>>{ List<Endpoint> endpoints; @Autowired public MyListEndpoints(List<Endpoint> endpoints) { super("myListEndpoints"); this.endpoints = endpoints; } @Override public List<Endpoint> invoke() { return this.endpoints; } }
[ { id: "myCustomEndpoint", enabled: true, sensitive: true }, { id: "mappings", sensitive: true, enabled: true }, { id: "env", sensitive: true, enabled: true }, { id: "health", sensitive: false, enabled: true, timeToLive: 1000 }, { id: "beans", sensitive: true, enabled: true }, { id: "info", sensitive: false, enabled: true }, { id: "metrics", sensitive: false, enabled: true }, { id: "trace", sensitive: true, enabled: true }, { id: "dump", sensitive: true, enabled: true }, { id: "autoconfig", sensitive: true, enabled: true }, { id: "shutdown", sensitive: true, enabled: false }, { id: "configprops", sensitive: true, enabled: true } ]
7. Actuator Example application
<?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.dineshonjava.sba</groupId> <artifactId>SpringBootActuator</artifactId> <version>0.0.1-SNAPSHOT</version> <packaging>jar</packaging> <name>SpringBootActuator</name> <description>SpringBootActuator project for Spring Boot Actuator</description> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>1.4.0.RELEASE</version> <relativePath/> <!-- lookup parent from repository --> </parent> <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-security</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>
#/info endpoint configuration endpoints.info.id=info endpoints.info.sensitive=false endpoints.info.enabled=true info.app.name=Spring Boot Actuator Application info.app.description=This is my first Working Spring Actuator Examples info.app.version=0.0.1-SNAPSHOT #/metrics endpoint configuration endpoints.metrics.id=metrics endpoints.metrics.sensitive=false endpoints.metrics.enabled=true #securing endpoints by spring security security.basic.enabled=true security.user.name=admin security.user.password=secret #/health endpoint configuration (Comment when you are using customized health check) endpoints.health.id=health endpoints.health.sensitive=false endpoints.health.enabled=true #Management for endpoints management.port=8080 management.context-path=/ management.security.enabled=true
https://github.com/DOJ-SoftwareConsultant/SpringBootActuator
8. Summary:
In this tutorial we had a first look at the interesting Actuator functionality provided by Spring Boot. I have explained about the basic concepts on actuators, endpoints, list of endpoints, creating custom endpoints, health check,metrics and provided a complete working example application for spring boot actuator.
Spring Boot Actuator Video: by Baeldung
Happy Spring Boot Learning!!!
Spring Boot Related Topics
- Introduction to Spring Boot
- Essentials and Key Components of Spring Boot
- Spring Boot CLI Installation and Hello World Example
- Spring Boot Initializr Web Interface
- Spring Boot Initializr With IDEs
- Spring Boot Initializr With Spring Boot CLI
- Installing Spring Boot
- Developing your first Spring Boot application
- External Configurations for Spring Boot Applications
- Logging Configuration in Spring Boot
- Spring Boot and Spring MVC
- Working with SQL Databases and Spring Boot
- MySQL Configurations
- Spring Data JPA using Spring Boot Application
- Spring Boot with NoSQL technologies
- Spring Cache Tutorial
- Spring Security Tutorial with Spring Boot
- Spring Boot and MongoDB in REST Application
- Complete Guide for Spring Boot Actuator
- Microservices with Spring Boot
Hi Dinesh,
As our requirement, We need to get the data from the metrics and send the status.
For eg, we have metrics like {“heap.committed”:480768,”heap.init”:262144,”heap.used”:294461,”heap”:3728384,”threads.peak”:37} and we have to read this memory usage from these metrics and send the status like WARN, HIGH.
my question is how to read the data from actuator URL
Actuator works only for http endpoints, to check if the internet facing endpoint is down or up, what is the approach we need to consider in that case.