{"id":59773,"date":"2020-08-21T15:27:47","date_gmt":"2020-08-21T15:27:47","guid":{"rendered":"https:\/\/www.baeldung.com\/?p=86046"},"modified":"2020-08-21T15:27:47","modified_gmt":"2020-08-21T15:27:47","slug":"health-indicators-in-spring-boot","status":"publish","type":"post","link":"https:\/\/itteacheritfreelance.hk\/wordpress\/index.php\/2020\/08\/21\/health-indicators-in-spring-boot\/","title":{"rendered":"Health Indicators in Spring Boot"},"content":{"rendered":"

<\/p>\n

1. Overview<\/h2>\n
<\/div>\n

Spring Boot provides a few different ways to inspect the status and health of a running application and its components. Among those approaches, the HealthContributor<\/a>\u00a0<\/em>and\u00a0HealthIndicator<\/a>\u00a0<\/em>APIs are two of the notable ones.<\/p>\n

In this tutorial, we’re going to get familiar with these APIs, learn how they work, and see how we can contribute custom information to them.<\/p>\n

2. Dependencies<\/h2>\n
<\/div>\n

Health information contributors are part of the Spring Boot actuator<\/a> module, so we need the appropriate Maven dependency<\/a>:<\/p>\n

<dependency>\r\n    <groupId>org.springframework.boot<\/groupId>\r\n    <artifactId>spring-boot-starter-actuator<\/artifactId>\r\n<\/dependency<\/code><\/pre>\n
3. Built-in\u00a0HealthIndicator<\/em>s<\/h2>\n
<\/div>\n
Out of the box, Spring Boot registers many\u00a0HealthIndicator<\/em>s to report the healthiness of a particular application aspect<\/strong>.<\/p>\n
Some of those indicators are almost always registered, such as DiskSpaceHealthIndicator<\/a>\u00a0<\/em>or\u00a0PingHealthIndicator<\/em><\/a>. The former reports the current state of the disk and the latter serves as a\u00a0ping endpoint for the application.<\/p>\n
On the other hand, Spring Boot registers some indicators conditionally<\/strong>. That is if some dependencies are on the classpath or some other conditions are met, Spring Boot might register a few other\u00a0HealthIndicator<\/em>s, too. For instance, if we’re using relational databases, then Spring Boot registers\u00a0DataSourceHealthIndicator<\/em><\/a>. Similarly, it’ll register\u00a0CassandraHealthIndicator<\/a>\u00a0<\/em>if we happen to use\u00a0Cassandra as our data store.<\/p>\n
In order to inspect the health status of a Spring Boot application, we can call the\u00a0\/actuator\/health\u00a0<\/em>endpoint<\/strong>. This endpoint will report an aggregated result of all registered\u00a0HealthIndicator<\/em>s.<\/p>\n
Also, to see the health report from one specific indicator, we can call the\u00a0\/actuator\/health\/{name}\u00a0<\/em>endpoint<\/strong>. For instance, calling the\u00a0\/actuator\/health\/diskSpace\u00a0<\/em>endpoint will return a status report from the\u00a0DiskSpaceHealthIndicator<\/em>:<\/p>\n
{\r\n  \"status\": \"UP\",\r\n  \"details\": {\r\n    \"total\": 499963170816,\r\n    \"free\": 134414831616,\r\n    \"threshold\": 10485760,\r\n    \"exists\": true\r\n  }\r\n}<\/code><\/pre>\n
4. Custom\u00a0HealthIndicator<\/em>s<\/h2>\n
<\/div>\n
In addition to the built-in ones, we can register custom\u00a0HealthIndicator<\/em>s\u00a0to report the health of a component or subsystem. In order to that, all we have to do is to register an implementation of the\u00a0HealthIndicator <\/em>interface\u00a0as a Spring bean<\/strong>.<\/p>\n
For instance, the following implementation reports a failure randomly:<\/p>\n
@Component\r\npublic class RandomHealthIndicator implements HealthIndicator {\r\n    @Override\r\n    public Health health() {\r\n        double chance = ThreadLocalRandom.current().nextDouble();\r\n        Health.Builder status = Health.up();\r\n        if (chance > 0.9) {\r\n            status = Health.down();\r\n        }\r\n        return status.build();\r\n    }\r\n}\r\n<\/code><\/pre>\n
According to the health report from this indicator, the application should be up only 90% of the time. Here we’re using Health<\/a>\u00a0<\/em>builders to report the health information.<\/p>\n
In reactive applications, however, we should register a bean of type\u00a0ReactiveHealthIndicator<\/em><\/a><\/strong>. The reactive\u00a0health()\u00a0<\/em>method returns a Mono<Health><\/a>\u00a0<\/em>instead of a simple\u00a0Health<\/em>. Other than that, other details are the same for both web application types.<\/p>\n
4.1. Indicator Name<\/h3>\n
<\/div>\n
To see the report for this particular indicator, we can call the\u00a0\/actuator\/health\/random\u00a0<\/em>endpoint. For instance, here’s what the API response might look like:<\/p>\n
{\"status\": \"UP\"}<\/code><\/pre>\n
The\u00a0random\u00a0<\/em>in the\u00a0\/actuator\/health\/random\u00a0<\/em>URL is the identifier for this indicator.\u00a0The identifier for a particular\u00a0HealthIndicator\u00a0<\/em><\/strong>implementation is equal to the bean name without the\u00a0HealthIndicator\u00a0<\/em><\/strong>suffix.\u00a0<\/strong>Since the bean name is\u00a0randomHealthIdenticator<\/em>, the\u00a0random\u00a0<\/em>prefix\u00a0will be the identifier.<\/p>\n
With this algorithm, if we change the bean name to, say,\u00a0rand<\/em>:<\/p>\n
@Component(\"rand\")\r\npublic class RandomHealthIndicator implements HealthIndicator {\r\n    \/\/ omitted\r\n}<\/code><\/pre>\n
Then the indicator identifier will be\u00a0rand\u00a0<\/em>instead of\u00a0random<\/em>.<\/p>\n
4.2. Disabling the Indicator<\/h3>\n
<\/div>\n
To disable a particular indicator, we can set the\u00a0“<\/em>management.health.<indicator_identifier>.enabled”\u00a0<\/em>configuration\u00a0property to\u00a0false<\/em><\/strong>. For instance, if we add the following to our\u00a0application.properties<\/em>:<\/p>\n
management.health.random.enabled=false<\/code><\/pre>\n
Then Spring Boot will disable the\u00a0RandomHealthIndicator<\/em>. To activate this configuration property, we should also add the\u00a0@ConditionalOnEnabledHealthIndicator<\/a>\u00a0<\/em>annotation on the indicator:<\/p>\n
@Component\r\n@ConditionalOnEnabledHealthIndicator(\"random\")\r\npublic class RandomHealthIndicator implements HealthIndicator { \r\n    \/\/ omitted\r\n}<\/code><\/pre>\n
Now if we call the\u00a0\/actuator\/health\/random<\/em>, Spring Boot will return a 404 Not Found HTTP response:<\/p>\n
@SpringBootTest\r\n@AutoConfigureMockMvc\r\n@TestPropertySource(properties = \"management.health.random.enabled=false\")\r\nclass DisabledRandomHealthIndicatorIntegrationTest {\r\n    @Autowired\r\n    private MockMvc mockMvc;\r\n    @Test\r\n    void givenADisabledIndicator_whenSendingRequest_thenReturns404() throws Exception {\r\n        mockMvc.perform(get(\"\/actuator\/health\/random\"))\r\n          .andExpect(status().isNotFound());\r\n    }\r\n}<\/code><\/pre>\n
Please note that disabling built-in or custom indicators is similar to each other. Therefore, we can apply the same configuration to the built-in indicators, too.<\/p>\n
4.3. Additional Details<\/h3>\n
<\/div>\n
In addition to reporting the status, we can attach additional key-value details using the\u00a0withDetail(key, value)<\/em><\/a>:<\/p>\n
public Health health() {\r\n    double chance = ThreadLocalRandom.current().nextDouble();\r\n    Health.Builder status = Health.up();\r\n    if (chance > 0.9) {\r\n        status = Health.down();\r\n    }\r\n    return status\r\n      .withDetail(\"chance\", chance)\r\n      .withDetail(\"strategy\", \"thread-local\")\r\n      .build();\r\n}<\/code><\/pre>\n
Here we’re adding two pieces of information to the status report. Also, we can achieve the same thing by passing a Map<String, Object>\u00a0<\/em>to the\u00a0withDetails(map)<\/a>\u00a0<\/em>method:<\/p>\n
Map<String, Object> details = new HashMap<>();\r\ndetails.put(\"chance\", chance);\r\ndetails.put(\"strategy\", \"thread-local\");\r\n        \r\nreturn status.withDetails(details).build();<\/code><\/pre>\n
Now if we call the\u00a0\/actuator\/health\/random<\/em>, we might see something like:<\/p>\n
{\r\n  \"status\": \"DOWN\",\r\n  \"details\": {\r\n    \"chance\": 0.9883560157173152,\r\n    \"strategy\": \"thread-local\"\r\n  }\r\n}<\/code><\/pre>\n
We can verify this behavior with an automated test, too:<\/p>\n
mockMvc.perform(get(\"\/actuator\/health\/random\"))\r\n  .andExpect(jsonPath(\"$.status\").exists())\r\n  .andExpect(jsonPath(\"$.details.strategy\").value(\"thread-local\"))\r\n  .andExpect(jsonPath(\"$.details.chance\").exists());<\/code><\/pre>\n
Sometimes an exception occurs while communicating to a system component such as Database or Disk. We can report such exceptions using the\u00a0withException(ex)<\/a>\u00a0<\/em>method:<\/p>\n
if (chance > 0.9) {\r\n    status.withException(new RuntimeException(\"Bad luck\"));\r\n}<\/code><\/pre>\n
We can also pass the exception to the\u00a0down(ex)<\/a>\u00a0<\/em>method we saw earlier:<\/p>\n
if (chance > 0.9) {\r\n    status = Health.down(new RuntimeException(\"Bad Luck\"));\r\n}<\/code><\/pre>\n
Now the health report will contain the stack trace:<\/p>\n
{\r\n  \"status\": \"DOWN\",\r\n  \"details\": {\r\n    \"error\": \"java.lang.RuntimeException: Bad Luck\",\r\n    \"chance\": 0.9603739107139401,\r\n    \"strategy\": \"thread-local\"\r\n  }\r\n}<\/code><\/pre>\n
4.4. Details Exposure<\/h3>\n
<\/div>\n
The\u00a0management.endpoint.health.show-details\u00a0<\/em>configuration property controls the level of details each health endpoint can expose.\u00a0<\/strong><\/p>\n
For instance, if we set this property to\u00a0always,\u00a0<\/em>then Spring Boot will always return the\u00a0details\u00a0<\/em>field in the health report, just like the above example.<\/p>\n
On the other hand, if we set this property to\u00a0never<\/em>, then Spring Boot will always omit the details<\/em> from the output<\/strong>. There is also the\u00a0when_authorized\u00a0<\/em>value which exposes the additional details<\/em> only for authorized users. A user is authorized if and only if:<\/p>\n