Spring Boot includes a number of additional features to help you monitor and manage your application when it’s pushed to production. You can choose to manage and monitor your application using HTTP endpoints, with JMX or even by remote shell (SSH or Telnet). Auditing, health and metrics gathering can be automatically applied to your application.
Actuator HTTP endpoints are only available with a Spring MVC-based application. In particular, it will not work with Jersey unless you enable Spring MVC as well.
46. Enabling production-ready features
The spring-boot-actuator module provides all of Spring Boot’s production-ready features. The simplest way to enable the features is to add a dependency to the spring-boot-starter-actuator
‘Starter’.
Definition of Actuator
An actuator is a manufacturing term, referring to a mechanical device for moving or controlling something. Actuators can generate a large amount of motion from a small change.
To add the actuator to a Maven based project, add the following ‘Starter’ dependency:
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
</dependencies>
For Gradle, use the declaration:
dependencies {
compile("org.springframework.boot:spring-boot-starter-actuator") }
47. Endpoints
Actuator endpoints allow you to monitor and interact with your application. Spring Boot includes a number of built-in endpoints and you can also add your own. For example the health endpoint provides basic application health information.
The way that endpoints are exposed will depend on the type of technology that you choose. Most applications choose HTTP monitoring, where the ID of the endpoint is mapped to a URL. For example, by default, the health endpoint will be mapped to /health.
The following technology agnostic endpoints are available:
ID Description Sensitive
Default actuator Provides a hypermedia-based “discovery page” for the
other endpoints. Requires Spring HATEOAS to be on the classpath.
true
auditevents Exposes audit events information for the current application. true autoconfig Displays an configuration report showing all
auto-configuration candidates and the reason why they ‘were’ or
‘were not’ applied.
true
beans Displays a complete list of all the Spring beans in your application.
true
configprops Displays a collated list of all @ConfigurationProperties. true
dump Performs a thread dump. true
env Exposes properties from Spring’s
ConfigurableEnvironment.
true
flyway Shows any Flyway database migrations that have been applied.
true
health Shows application health information (when the application is secure, a simple ‘status’ when accessed over an
unauthenticated connection or full message details when authenticated).
false
info Displays arbitrary application info. false
loggers Shows and modifies the configuration of loggers in the application.
true
liquibase Shows any Liquibase database migrations that have been applied.
true
metrics Shows ‘metrics’ information for the current application. true mappings Displays a collated list of all @RequestMapping paths. true
ID Description Sensitive Default shutdown Allows the application to be gracefully shutdown (not enabled
by default).
true
trace Displays trace information (by default the last 100 HTTP requests).
true
If you are using Spring MVC, the following additional endpoints can also be used:
ID Description Sensitive
Default docs Displays documentation, including example requests and
responses, for the Actuator’s endpoints. Requires spring-boot-actuator-docs to be on the classpath.
false
heapdump Returns a GZip compressed hprof heap dump file. true jolokia Exposes JMX beans over HTTP (when Jolokia is on the
classpath).
true
logfile Returns the contents of the logfile (if logging.file or logging.path properties have been set). Supports the use of the HTTP Range header to retrieve part of the log file’s content.
true
Note
Depending on how an endpoint is exposed, the sensitive property may be used as a security hint. For example, sensitive endpoints will require a username/password when they are accessed over HTTP (or simply disabled if web security is not enabled).
47.1 Customizing endpoints
Endpoints can be customized using Spring properties. You can change if an endpoint is enabled, if it is considered sensitive and even its id.
For example, here is an application.properties that changes the sensitivity and id of the beans endpoint and also enables shutdown.
endpoints.beans.id=springbeans endpoints.beans.sensitive=false endpoints.shutdown.enabled=true
Note
endpoints.enabled=false endpoints.info.enabled=true
Likewise, you can also choose to globally set the “sensitive” flag of all endpoints. By default, the sensitive flag depends on the type of endpoint (see the table above). For example, to mark all endpoints as sensitive except info:
endpoints.sensitive=true endpoints.info.sensitive=false
47.2 Hypermedia for actuator MVC endpoints
If endpoints.hypermedia.enabled is set to true and Spring HATEOAS is on the classpath (e.g.
through the spring-boot-starter-hateoas or if you are using Spring Data REST) then the HTTP endpoints from the Actuator are enhanced with hypermedia links, and a “discovery page” is added with links to all the endpoints. The “discovery page” is available on /actuator by default. It is implemented as an endpoint, allowing properties to be used to configure its path (endpoints.actuator.path) and whether or not it is enabled (endpoints.actuator.enabled).
When a custom management context path is configured, the “discovery page” will automatically move from /actuator to the root of the management context. For example, if the management context path is /management then the discovery page will be available from /management.
If the HAL Browser is on the classpath via its webjar (org.webjars:hal-browser), or via the spring-data-rest-hal-browser then an HTML “discovery page”, in the form of the HAL Browser, is also provided.
47.3 CORS support
Cross-origin resource sharing (CORS) is a W3C specification that allows you to specify in a flexible way what kind of cross domain requests are authorized. Actuator’s MVC endpoints can be configured to support such scenarios.
CORS support is disabled by default and is only enabled once the endpoints.cors.allowed-origins property has been set. The configuration below permits GET and POST calls from the example.com domain:
endpoints.cors.allowed-origins=http://example.com endpoints.cors.allowed-methods=GET,POST
Tip
Check EndpointCorsProperties for a complete list of options.
47.4 Adding custom endpoints
If you add a @Bean of type Endpoint then it will automatically be exposed over JMX and HTTP (if there is an server available). An HTTP endpoints can be customized further by creating a bean of type MvcEndpoint. Your MvcEndpoint is not a @Controller but it can use @RequestMapping (and
@Managed*) to expose resources.
Tip
If you are doing this as a library feature consider adding a configuration class annotated with
@ManagementContextConfiguration to /META-INF/spring.factories under the key
org.springframework.boot.actuate.autoconfigure.ManagementContextConfiguration.
If you do that then the endpoint will move to a child context with all the other MVC endpoints if your users ask for a separate management port or address. A configuration declared this way can be a WebConfigurerAdapter if it wants to add static resources (for instance) to the management endpoints.
47.5 Health information
Health information can be used to check the status of your running application. It is often used by monitoring software to alert someone if a production system goes down. The default information exposed by the health endpoint depends on how it is accessed. For an unauthenticated connection in a secure application a simple ‘status’ message is returned, and for an authenticated connection additional details are also displayed (see Section 48.7, “HTTP health endpoint format and access restrictions” for HTTP details).
Health information is collected from all HealthIndicator beans defined in your ApplicationContext. Spring Boot includes a number of auto-configured HealthIndicators and you can also write your own. By default, the final system state is derived by the HealthAggregator which sorts the statuses from each HealthIndicator based on an ordered list of statuses. The first status in the sorted list is used as the overall health status. If no HealthIndicator returns a status that is known to the HealthAggregator, an UNKNOWN status is used.
47.6 Security with HealthIndicators
Information returned by HealthIndicators is often somewhat sensitive in nature. For example, you probably don’t want to publish details of your database server to the world. For this reason, by default, only the health status is exposed over an unauthenticated HTTP connection. If you are happy for complete health information to always be exposed you can set endpoints.health.sensitive to false.
Health responses are also cached to prevent “denial of service” attacks. Use the endpoints.health.time-to-live property if you want to change the default cache period of 1000 milliseconds.