Run specific health check

This commit improves the `health` endpoint to run health check for a
particular component or, if that component is itself a composite, an
instance of that component.

Concretely, it is now possible to issue a `GET` on
`/actuator/health/{component}` and
`/actuator/health/{component}/instance` to retrieve the health of a
component or an instance of a composite component, respectively.

If details cannot be showed for the current user, any request leads to a
404 and does not invoke the health check at all.

Closes gh-8865

Author: snicoll

spring-boot-project/spring-boot-actuator-autoconfigure/src/main/asciidoc/endpoints/health.adoc

@@ -1,13 +1,11 @@
 [[health]]
 = Health (`health`)
-
 The `health` endpoint provides detailed information about the health of the application.
 
 
 
 [[health-retrieving]]
-== Retrieving the Health
-
+== Retrieving the Health of the application
 To retrieve the health of the application, make a `GET` request to `/actuator/health`,
 as shown in the following curl-based example:
 
@@ -21,9 +19,56 @@ include::{snippets}health/http-response.adoc[]
 
 [[health-retrieving-response-structure]]
 === Response Structure
-
 The response contains details of the health of the application. The following table
 describes the structure of the response:
 
 [cols="2,1,3"]
 include::{snippets}health/response-fields.adoc[]
+
+
+
+[[health-retrieving-component]]
+== Retrieving the Health of a component
+To retrieve the health of a particular component of the application, make a `GET` request
+to `/actuator/health/{component}`, as shown in the following curl-based example:
+
+include::{snippets}health/component/curl-request.adoc[]
+
+The resulting response is similar to the following:
+
+include::{snippets}health/component/http-response.adoc[]
+
+
+
+[[health-retrieving-component-response-structure]]
+=== Response Structure
+The response contains details of the health of a particular component of the application.
+The following table describes the structure of the response:
+
+[cols="2,1,3"]
+include::{snippets}health/component/response-fields.adoc[]
+
+
+
+[[health-retrieving-component-instance]]
+== Retrieving the Health of a component instance
+If a particular component consists of multiple instances (as the `broker` indicator in
+the example above), the health of a particular instance of that component can be retrieved
+by issuing a `GET` request to `/actuator/health/{component}/{instance}`, as shown in the
+following curl-based example:
+
+include::{snippets}health/instance/curl-request.adoc[]
+
+The resulting response is similar to the following:
+
+include::{snippets}health/instance/http-response.adoc[]
+
+
+
+[[health-retrieving-component-instance-response-structure]]
+=== Response Structure
+The response contains details of the health of an instance of a particular component of
+the application. The following table describes the structure of the response:
+
+[cols="2,1,3"]
+include::{snippets}health/instance/response-fields.adoc[]

spring-boot-project/spring-boot-actuator-autoconfigure/src/test/java/org/springframework/boot/actuate/autoconfigure/cloudfoundry/CloudFoundryWebEndpointDiscovererTests.java

@@ -58,7 +58,7 @@ public void getEndpointsShouldAddCloudFoundryHealthExtension() {
 			assertThat(endpoints.size()).isEqualTo(2);
 			for (ExposableWebEndpoint endpoint : endpoints) {
 				if (endpoint.getId().equals("health")) {
-					WebOperation operation = endpoint.getOperations().iterator().next();
+					WebOperation operation = findMainReadOperation(endpoint);
 					assertThat(operation.invoke(new InvocationContext(
 							mock(SecurityContext.class), Collections.emptyMap())))
 									.isEqualTo("cf");
@@ -67,6 +67,16 @@ public void getEndpointsShouldAddCloudFoundryHealthExtension() {
 		});
 	}
 
+	private WebOperation findMainReadOperation(ExposableWebEndpoint endpoint) {
+		for (WebOperation operation : endpoint.getOperations()) {
+			if (operation.getRequestPredicate().getPath().equals("health")) {
+				return operation;
+			}
+		}
+		throw new IllegalStateException("No main read operation found from "
+				+ endpoint.getOperations());
+	}
+
 	private void load(Class<?> configuration,
 			Consumer<CloudFoundryWebEndpointDiscoverer> consumer) {
 		this.load((id) -> null, (id) -> id, configuration, consumer);

spring-boot-project/spring-boot-actuator-autoconfigure/src/test/java/org/springframework/boot/actuate/autoconfigure/cloudfoundry/reactive/ReactiveCloudFoundryActuatorAutoConfigurationTests.java

@@ -284,8 +284,9 @@ public void healthEndpointInvokerShouldBeCloudFoundryWebExtension() {
 					Collection<ExposableWebEndpoint> endpoints = getHandlerMapping(
 							context).getEndpoints();
 					ExposableWebEndpoint endpoint = endpoints.iterator().next();
-					WebOperation webOperation = endpoint.getOperations().iterator()
-							.next();
+					assertThat(endpoint.getOperations()).hasSize(3);
+					WebOperation webOperation = findOperationWithRequestPath(endpoint,
+							"health");
 					Object invoker = ReflectionTestUtils.getField(webOperation,
 							"invoker");
 					assertThat(ReflectionTestUtils.getField(invoker, "target"))
@@ -346,6 +347,17 @@ private CloudFoundryWebFluxEndpointHandlerMapping getHandlerMapping(
 				CloudFoundryWebFluxEndpointHandlerMapping.class);
 	}
 
+	private WebOperation findOperationWithRequestPath(ExposableWebEndpoint endpoint,
+			String requestPath) {
+		for (WebOperation operation : endpoint.getOperations()) {
+			if (operation.getRequestPredicate().getPath().equals(requestPath)) {
+				return operation;
+			}
+		}
+		throw new IllegalStateException("No operation found with request path "
+				+ requestPath + " from " + endpoint.getOperations());
+	}
+
 	@Configuration
 	static class TestConfiguration {
 

spring-boot-project/spring-boot-actuator-autoconfigure/src/test/java/org/springframework/boot/actuate/autoconfigure/cloudfoundry/servlet/CloudFoundryActuatorAutoConfigurationTests.java

@@ -279,8 +279,9 @@ public void healthEndpointInvokerShouldBeCloudFoundryWebExtension() {
 									CloudFoundryWebEndpointServletHandlerMapping.class)
 							.getEndpoints();
 					ExposableWebEndpoint endpoint = endpoints.iterator().next();
-					WebOperation webOperation = endpoint.getOperations().iterator()
-							.next();
+					assertThat(endpoint.getOperations()).hasSize(3);
+					WebOperation webOperation = findOperationWithRequestPath(endpoint,
+							"health");
 					Object invoker = ReflectionTestUtils.getField(webOperation,
 							"invoker");
 					assertThat(ReflectionTestUtils.getField(invoker, "target"))
@@ -294,6 +295,17 @@ private CloudFoundryWebEndpointServletHandlerMapping getHandlerMapping(
 				CloudFoundryWebEndpointServletHandlerMapping.class);
 	}
 
+	private WebOperation findOperationWithRequestPath(ExposableWebEndpoint endpoint,
+			String requestPath) {
+		for (WebOperation operation : endpoint.getOperations()) {
+			if (operation.getRequestPredicate().getPath().equals(requestPath)) {
+				return operation;
+			}
+		}
+		throw new IllegalStateException("No operation found with request path "
+				+ requestPath + " from " + endpoint.getOperations());
+	}
+
 	@Configuration
 	static class TestConfiguration {
 

spring-boot-project/spring-boot-actuator-autoconfigure/src/test/java/org/springframework/boot/actuate/autoconfigure/endpoint/web/documentation/HealthEndpointDocumentationTests.java

@@ -17,13 +17,18 @@
 package org.springframework.boot.actuate.autoconfigure.endpoint.web.documentation;
 
 import java.io.File;
+import java.util.Arrays;
+import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 
 import javax.sql.DataSource;
 
 import org.junit.Test;
 
 import org.springframework.boot.actuate.health.CompositeHealthIndicator;
+import org.springframework.boot.actuate.health.DefaultHealthIndicatorRegistry;
+import org.springframework.boot.actuate.health.Health;
 import org.springframework.boot.actuate.health.HealthEndpoint;
 import org.springframework.boot.actuate.health.HealthIndicator;
 import org.springframework.boot.actuate.health.HealthIndicatorRegistryFactory;
@@ -35,6 +40,7 @@
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.context.annotation.Import;
+import org.springframework.restdocs.payload.FieldDescriptor;
 
 import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
@@ -47,9 +53,17 @@
  * Tests for generating documentation describing the {@link HealthEndpoint}.
  *
  * @author Andy Wilkinson
+ * @author Stephane Nicoll
  */
 public class HealthEndpointDocumentationTests extends MockMvcEndpointDocumentationTests {
 
+	private static final List<FieldDescriptor> componentFields = Arrays.asList(
+			fieldWithPath("status")
+					.description("Status of a specific part of the application"),
+			subsectionWithPath("details").description(
+					"Details of the health of a specific part of the"
+							+ " application."));
+
 	@Test
 	public void health() throws Exception {
 		this.mockMvc.perform(get("/actuator/health")).andExpect(status().isOk())
@@ -66,6 +80,19 @@ public void health() throws Exception {
 										+ " application."))));
 	}
 
+	@Test
+	public void healthComponent() throws Exception {
+		this.mockMvc.perform(get("/actuator/health/db")).andExpect(status().isOk())
+				.andDo(document("health/component", responseFields(componentFields)));
+	}
+
+	@Test
+	public void healthComponentInstance() throws Exception {
+		this.mockMvc.perform(get("/actuator/health/broker/us1"))
+				.andExpect(status().isOk())
+				.andDo(document("health/instance", responseFields(componentFields)));
+	}
+
 	@Configuration
 	@Import(BaseDocumentationConfiguration.class)
 	@ImportAutoConfiguration(DataSourceAutoConfiguration.class)
@@ -84,11 +111,22 @@ public DiskSpaceHealthIndicator diskSpaceHealthIndicator() {
 		}
 
 		@Bean
-		public DataSourceHealthIndicator dataSourceHealthIndicator(
+		public DataSourceHealthIndicator dbHealthIndicator(
 				DataSource dataSource) {
 			return new DataSourceHealthIndicator(dataSource);
 		}
 
+		@Bean
+		public CompositeHealthIndicator brokerHealthIndicator() {
+			Map<String, HealthIndicator> indicators = new LinkedHashMap<>();
+			indicators.put("us1", () -> Health.up().withDetail("version", "1.0.2")
+					.build());
+			indicators.put("us2", () -> Health.up().withDetail("version", "1.0.4")
+					.build());
+			return new CompositeHealthIndicator(new OrderedHealthAggregator(),
+					new DefaultHealthIndicatorRegistry(indicators));
+		}
+
 	}
 
 }