From 988fc18f8c9bffe0278157f8d2a531c33aa4042d Mon Sep 17 00:00:00 2001 From: Andy Wilkinson Date: Fri, 26 Jan 2018 12:10:56 +0000 Subject: [PATCH] Simplify endpoint enablement and update reference documentation Closes gh-11755 --- .../jmx/JmxEndpointAutoConfiguration.java | 2 - .../web/WebEndpointAutoConfiguration.java | 2 - ...itional-spring-configuration-metadata.json | 12 - .../appendix-application-properties.adoc | 2 - .../asciidoc/production-ready-features.adoc | 256 ++++++++++++++---- 5 files changed, 202 insertions(+), 72 deletions(-) diff --git a/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/java/org/springframework/boot/actuate/autoconfigure/endpoint/jmx/JmxEndpointAutoConfiguration.java b/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/java/org/springframework/boot/actuate/autoconfigure/endpoint/jmx/JmxEndpointAutoConfiguration.java index 660bc88efd..3540883c34 100644 --- a/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/java/org/springframework/boot/actuate/autoconfigure/endpoint/jmx/JmxEndpointAutoConfiguration.java +++ b/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/java/org/springframework/boot/actuate/autoconfigure/endpoint/jmx/JmxEndpointAutoConfiguration.java @@ -40,7 +40,6 @@ import org.springframework.boot.actuate.endpoint.jmx.annotation.JmxEndpointDisco import org.springframework.boot.autoconfigure.AutoConfigureAfter; import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; -import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.boot.autoconfigure.condition.ConditionalOnSingleCandidate; import org.springframework.boot.autoconfigure.jmx.JmxAutoConfiguration; import org.springframework.boot.context.properties.EnableConfigurationProperties; @@ -58,7 +57,6 @@ import org.springframework.util.ObjectUtils; */ @AutoConfigureAfter(JmxAutoConfiguration.class) @EnableConfigurationProperties(JmxEndpointProperties.class) -@ConditionalOnProperty(name = "management.endpoints.jmx.enabled", matchIfMissing = true) public class JmxEndpointAutoConfiguration { private final ApplicationContext applicationContext; diff --git a/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/java/org/springframework/boot/actuate/autoconfigure/endpoint/web/WebEndpointAutoConfiguration.java b/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/java/org/springframework/boot/actuate/autoconfigure/endpoint/web/WebEndpointAutoConfiguration.java index 85273f20ce..4286838ad3 100644 --- a/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/java/org/springframework/boot/actuate/autoconfigure/endpoint/web/WebEndpointAutoConfiguration.java +++ b/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/java/org/springframework/boot/actuate/autoconfigure/endpoint/web/WebEndpointAutoConfiguration.java @@ -46,7 +46,6 @@ import org.springframework.boot.actuate.endpoint.web.annotation.WebEndpointDisco import org.springframework.boot.autoconfigure.AutoConfigureAfter; import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; -import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication; import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication.Type; import org.springframework.boot.context.properties.EnableConfigurationProperties; @@ -66,7 +65,6 @@ import org.springframework.context.annotation.Configuration; @ConditionalOnWebApplication @AutoConfigureAfter(EndpointAutoConfiguration.class) @EnableConfigurationProperties(WebEndpointProperties.class) -@ConditionalOnProperty(name = "management.endpoints.web.enabled", matchIfMissing = true) public class WebEndpointAutoConfiguration { private static final List MEDIA_TYPES = Arrays diff --git a/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/resources/META-INF/additional-spring-configuration-metadata.json b/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/resources/META-INF/additional-spring-configuration-metadata.json index 2d8fcc3d89..db5773823d 100644 --- a/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/resources/META-INF/additional-spring-configuration-metadata.json +++ b/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/resources/META-INF/additional-spring-configuration-metadata.json @@ -27,22 +27,10 @@ "type": "java.lang.Boolean", "description": "Whether to enable or disable all endpoints by default." }, - { - "name": "management.endpoints.jmx.enabled", - "type": "java.lang.Boolean", - "description": "Whether JMX endpoints are enabled.", - "defaultValue": true - }, { "name": "management.endpoints.jmx.expose", "defaultValue": "*" }, - { - "name": "management.endpoints.web.enabled", - "type": "java.lang.Boolean", - "description": "Whether web endpoints are enabled.", - "defaultValue": true - }, { "name": "management.endpoints.web.expose", "defaultValue": [ diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/appendix-application-properties.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/appendix-application-properties.adoc index f6b7c07382..c38b1c7520 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/appendix-application-properties.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/appendix-application-properties.adoc @@ -1151,7 +1151,6 @@ content into your application. Rather, pick only the properties that you need. management.endpoints.enabled-by-default= # Enable or disable all endpoints by default. # ENDPOINTS JMX CONFIGURATION ({sc-spring-boot-actuator-autoconfigure}/endpoint/jmx/JmxEndpointProperties.{sc-ext}[JmxEndpointProperties]) - management.endpoints.jmx.enabled=true # Whether JMX endpoints are enabled. management.endpoints.jmx.expose=* # Endpoint IDs that should be exposed or '*' for all. management.endpoints.jmx.exclude= # Endpoint IDs that should be excluded. management.endpoints.jmx.domain=org.springframework.boot # Endpoints JMX domain name. Fallback to 'spring.jmx.default-domain' if set. @@ -1159,7 +1158,6 @@ content into your application. Rather, pick only the properties that you need. management.endpoints.jmx.unique-names=false # Whether to ensure that ObjectNames are modified in case of conflict. # ENDPOINTS WEB CONFIGURATION ({sc-spring-boot-actuator-autoconfigure}/endpoint/web/WebEndpointProperties.{sc-ext}[WebEndpointProperties]) - management.endpoints.web.enabled=true # Whether web endpoints are enabled management.endpoints.web.expose=info,health # Endpoint IDs that should be exposed or '*' for all. management.endpoints.web.exclude= # Endpoint IDs that should be excluded. management.endpoints.web.base-path=/actuator # Base path for Web endpoints. Relative to server.servlet.context-path or management.server.servlet.context-path if management.server.port is configured. diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc index 38fc8f3192..4cfe10b6b1 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc @@ -53,122 +53,283 @@ Actuator endpoints let you monitor and interact with your application. Spring Bo includes a number of built-in endpoints and lets you add your own. For example, the `health` endpoint provides basic application health information. -The way that endpoints are exposed depends on the type of technology that you choose. -Most applications choose HTTP monitoring, where the ID of the endpoint along with a -prefix of `/actuator` is mapped to a URL. For example, by default, the `health` -endpoint is mapped to `/actuator/health`. +Each individual endpoint can be <>. This controls whether or not the endpoint is created and its bean exists in +the application context. To be remotely accessible an endpoint also has to be +<>. The following technology-agnostic endpoints are available: -[cols="2,5"] +[cols="2,5,2"] |=== -| ID | Description +| ID | Description | Enabled by default |`auditevents` |Exposes audit events information for the current application. +|Yes |`beans` |Displays a complete list of all the Spring beans in your application. +|Yes |`conditions` |Shows the conditions that were evaluated on configuration and auto-configuration classes and the reasons why they did or did not match. +|Yes |`configprops` |Displays a collated list of all `@ConfigurationProperties`. +|Yes |`env` |Exposes properties from Spring's `ConfigurableEnvironment`. +|Yes |`flyway` |Shows any Flyway database migrations that have been applied. +|Yes |`health` |Shows application health information. +|Yes |`info` |Displays arbitrary application info. +|Yes |`loggers` |Shows and modifies the configuration of loggers in the application. +|Yes |`liquibase` |Shows any Liquibase database migrations that have been applied. +|Yes |`metrics` |Shows '`metrics`' information for the current application. +|Yes |`mappings` |Displays a collated list of all `@RequestMapping` paths. +|Yes |`scheduledtasks` |Displays the scheduled tasks in your application. +|Yes |`sessions` |Allows retrieval and deletion of user sessions from a Spring Session-backed session store. Not available when using Spring Session's support for reactive web applications. +|Yes |`shutdown` -|Lets the application be gracefully shutdown (not enabled by default). +|Lets the application be gracefully shutdown. +|No |`threaddump` |Performs a thread dump. +|Yes |`trace` |Displays HTTP trace information (by default, the last 100 HTTP requests). +|Yes + |=== If your application is a web application (Spring MVC, Spring WebFlux, or Jersey), you can use the following additional endpoints: -[cols="2,5"] +[cols="2,5,2"] |=== -| ID | Description +| ID | Description | Enabled by default |`heapdump` |Returns a GZip compressed `hprof` heap dump file. +|Yes + +|`jolokia` +|Exposes JMX beans over HTTP (when Jolokia is on the classpath, not availble for WebFlux). +|Yes |`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. +|Yes |`prometheus` |Exposes metrics in a format that can be scraped by a Prometheus server. - - -|`jolokia` -|Exposes JMX beans over HTTP (when Jolokia is on the classpath, not availble for WebFlux). +|Yes |=== - To learn more about the Actuator's endpoints and their request and response formats, please refer to the separate API documentation ({spring-boot-actuator-api}/html[HTML] or {spring-boot-actuator-api}/pdf/spring-boot-actuator-web-api.pdf[PDF]). +[[production-ready-endpoints-enabling-endpoints]] +=== Enabling Endpoints +By default, all endpoints except for `shutdown` are enabled. To configure the enablement +of an endpoint, use its `management.endpoints..enabled` property. The following +example enables the `shutdown` endpoint: + +[source,properties,indent=0] +---- + management.endpoint.shutdown.enabled=true +---- + +If you prefer endpoint enablement to be opt-in rather than opt-out, set the +`management.endpoints.enabled-by-default` property to `false` and use individual endpoint +`enabled` properties to opt back in. The following example enables the `info` endpoint and +disables all other endpoints: + +[source,properties,indent=0] +---- + management.endpoints.enabled-by-default=false + management.endpoint.info.enabled=true +---- + +NOTE: Disabled endpoints are removed entirely from the application context. If you want +to change only the technologies over which an endpoint is exposed, use the +<> +instead. + + + [[production-ready-endpoints-exposing-endpoints]] === Exposing Endpoints Since Endpoints may contain sensitive information, careful consideration should be given -about when to expose them. By default, Spring Boot exposes all enabled endpoints -over JMX but only the `health` and `info` endpoints over HTTP. +about when to expose them. The following table shows the default exposure for the built-in +endpoints: -To change the endpoints that are exposed, you can use the `expose` and `exclude` property -for the technology. For example, to only expose the `health` over JMX you would set the -following property: +[cols="1,1,1"] +|=== +| ID | JMX | Web + +|`auditevents` +|Yes +|No + +|`beans` +|Yes +|No + +|`conditions` +|Yes +|No + +|`configprops` +|Yes +|No + +|`env` +|Yes +|No + +|`flyway` +|Yes +|No + +|`health` +|Yes +|Yes + +|`heapdump` +|N/A +|No + +|`info` +|Yes +|Yes + +|`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 + +|`threaddump` +|Yes +|No + +|`trace` +|Yes +|No + +|=== + +To change which endpoints are exposed, use the following technology-specific `expose` and +`exclude` properties: + +[cols="3,1"] +|=== +|Property | Default + +|`management.endpoints.jmx.exclude` +| + +|`management.endpoints.jmx.expose` +| `*` + +|`management.endpoints.web.exclude` +| + +|`management.endpoints.web.expose` +| `info, health` + +|=== + +The `expose` property lists the IDs of the endpoints that are exposed. The `exclude` +property lists the IDs of the endpoints that should not be exposed. The `exclude` +property takes precedence over the `expose` property. + +For example, to stop exposing all endpoints over JMX and only expose the `health` +endpoint, use the following property: -.application.properties [source,properties,indent=0] ---- management.endpoints.jmx.expose=health ---- -The `*` character can be used to indicate all endpoints. For example, to expose everything -over HTTP except the `env` endpoint, you would use the following properties: +`*` can be used to select all endpoints. For example, to expose everything over HTTP +except the `env` endpoint, use the following properties: -.application.properties [source,properties,indent=0] ---- management.endpoints.web.expose=* @@ -186,10 +347,11 @@ register an `EndpointFilter` bean. [[production-ready-endpoints-security]] === Securing HTTP Endpoints You should take care to secure HTTP endpoints in the same way that you would any other -sensitive URL. If Spring Security is present, endpoints are secured by default using Spring Security’s -content-negotiation strategy. If you wish to configure custom security for HTTP endpoints, for example, only allow users -with a certain role to access them, Spring Boot provides some convenient `RequestMatcher` objects that can be used in combination with -Spring Security. +sensitive URL. If Spring Security is present, endpoints are secured by default using +Spring Security’s content-negotiation strategy. If you wish to configure custom security +for HTTP endpoints, for example, only allow users with a certain role to access them, +Spring Boot provides some convenient `RequestMatcher` objects that can be used in +combination with Spring Security. A typical Spring Security configuration might look something like the following example: @@ -225,8 +387,9 @@ endpoints can be accessed without requiring authentication. You can do so by cha management.endpoints.web.expose=* ---- -Additionally, if Spring Security is present, you would need to add custom security configuration -that allows unauthenticated access to the endpoints. For example, +Additionally, if Spring Security is present, you would need to add custom security +configuration that allows unauthenticated access to the endpoints as shown in the +following example: [source,java,indent=0] ---- @@ -244,38 +407,22 @@ that allows unauthenticated access to the endpoints. For example, -[[production-ready-customizing-endpoints]] -=== Customizing Endpoints -Endpoints can be customized by using Spring properties. You can change whether an -endpoint is `enabled` and the amount of time for which it caches responses. - -For example, the following `application.properties` file changes the time-to-live of the -`beans` endpoint to 10 seconds and also enables `shutdown`: +[[production-ready-endpoints-caching]] +=== Configuring Endpoints +Endpoints automatically cache responses to read operations that do not take any +parameters. To configure the amount of time for which an endpoint will cache a response, +use its `cache.time-to-live` property. The following example sets the time-to-live of +the `beans` endpoint's cache to 10 seconds: +.application.properties [source,properties,indent=0] ---- management.endpoint.beans.cache.time-to-live=10s - management.endpoint.shutdown.enabled=true ---- NOTE: The prefix `management.endpoint.` is used to uniquely identify the endpoint that is being configured. -By default, all endpoints except for `shutdown` are enabled. If you prefer to -specifically "`opt-in`" endpoint enablement, you can use the -`management.endpoints.enabled-by-default` property. For example, the following settings -disable _all_ endpoints except for `info`: - -[source,properties,indent=0] ----- - management.endpoints.enabled-by-default=false - management.endpoint.info.enabled=true ----- - -NOTE: Disabled endpoints are removed entirely from the `ApplicationContext`. If you want -to change only the technologies over which an endpoint is exposed, you can use the -`expose` and `exclude` properties (see <>). - [[production-ready-endpoint-hypermedia]] @@ -418,6 +565,7 @@ The following `HealthIndicators` are auto-configured by Spring Boot when appropr |{sc-spring-boot-actuator}/solr/SolrHealthIndicator.{sc-ext}[`SolrHealthIndicator`] |Checks that a Solr server is up. + |=== TIP: You can disable them all by setting the `management.health.defaults.enabled` @@ -839,11 +987,11 @@ settings show an example of doing so in `application.properties`: [[production-ready-disable-jmx-endpoints]] === Disabling JMX Endpoints If you do not want to expose endpoints over JMX, you can set the -`management.endpoints.jmx.enabled` property to `false`, as shown in the following example: +`management.endpoints.jmx.exclude` property to `*`, as shown in the following example: [source,properties,indent=0] ---- - management.endpoints.jmx.enabled=false + management.endpoints.jmx.exclude=* ----