Spring Boot Actuator’s Neo4jHealthIndicator

25 November 2017 · 4 min read

Spring and Spring Boot have become the Swiss Army knife of Java software development, offering dozens of useful modules across a wide range of concerns.

One such module is Spring Boot Actuator, a sub-project of Spring Boot, that offers built-in, production-grade functionality to help monitor and interact with an application. Numerous endpoints are included that provide a wealth of information that, among others, include auditing, configuration, environment, and health details.

The /health Endpoint

One particularly useful endpoint is /health, which displays information on the application’s overall health and can be used by monitoring software to generate alerts should a system component become unavailable. Health information is collected from all HealthIndicator beans defined in the ApplicationContext. Spring Boot Actuator includes a number of auto-configured HealthIndicators as well as provides for custom implementations.

Starting with Spring Boot 2.0, a Neo4jHealthIndicator for the Neo4j database, developed and contributed by GraphAware, is provided out of the box. This means that, for projects that make use of Spring Boot 2.0 and Neo4j, each time the /health endpoint is invoked a simple Cypher statement is executed, validating that Neo4j is available and that the application can access it successfully.

Figure 1 shows the output of the /health endpoint, including the Neo4jHealthIndicator’s status and details that Neo4j is available (“status: UP”). The result of the Cypher validation query, which simply returns the count of nodes in the database, is also included.

Trying It Out: Existing Applications

Taking advantage of the Neo4jHealthIndicator in an existing Spring Boot 2.x application is straightforward due to Spring Boot’s autoconfiguration and starters. Simply ensure that the spring-boot-starter-actuator and the required Neo4j dependencies are included in your build system (such as Maven or Gradle) and that the connection to Neo4j is configured correctly. Next, ensure that web access to the /health endpoint is enabled by updating the application’s application.properties. To enable web access to the /health endpoint only, add:

endpoints.health.web.enabled=true

To enable web access to all actuator endpoints, add:

endpoints.default.web.enabled=true

Finally, restart the application and browser to either http://localhost:8080/application or http://localhost:8080/application/health.

Trying It Out: A Sample Application

For those without an existing Spring Boot 2 application to experiment with the following steps will guide you through exploring and making use of the Neo4jHealthIndicator.

Use Spring’s Initializr, a simple web UI for configuring and generating Spring applications, to generate a sample project:
1. Visit https://start.spring.io. Click “Switch to the full version” on the lower portion of the page.
2. Configure Initializr to generate a Java web project, use the latest version of Spring Boot 2, and include Web, Neo4j and Actuator dependencies.
3. Click “Generate Project”
Extract the downloaded project and import it into your favorite IDE.
Modify the project’s src/main/resources/application.properties to contain:
```
  spring.data.neo4j.uri=http://localhost:7474
  spring.data.neo4j.username=neo4j
  spring.data.neo4j.password=neo4j
  endpoints.default.web.enabled=true
```
Because the project has Neo4j dependencies on the classpath, Spring Boot will automatically configure a connection to the Neo4j database. Should your Neo4j connection details differ than Spring Boot’s defaults, alter the properties above as needed. Ensure you have the connection details configured correctly, as specified in the documentation, as well as the necessary driver dependencies included, or the application will fail to start.

In a departure from previous versions, Spring Boot 2.0 disables the web access of actuator endpoints by default. Setting the ‘endpoints.default.web.enabled’ property to true, as we’ve done above, enables browser-based access to all endpoints. Actuator endpoints can also be enabled on a per-endpoint basis; in our case use “endpoints.health.web.enabled=true”.
Start Neo4j.
Compile, build, and start the sample application. If you are using Maven, use “mvn clean spring-boot:run”.
Browse to http://localhost:8080/application

What is shown is a “discovery page” with links to endpoints and the application information they each provide. Of interest to us is the /application/health endpoint.
Click http://localhost:8080/application/health

Similar to Figure 1, within the displayed JSON response is a “neo4j” section containing the status (“UP” or “DOWN”) and details as returned from the validation Cypher query, such as the count of nodes within the database.
Shut down Neo4j
Refresh http://localhost:8080/application/health

Because Neo4j has been shut down, when the /health endpoint is invoked the underlying Neo4jHealthIndicator is unable to successfully execute the validation Cypher statement against Neo4j.

As seen in Figure 2, when Neo4j is unavailable the Neo4jHealthIndicator reports Neo4j with a status of “DOWN” along with a details message.

Security

It’s worth noting that some actuator endpoints provide sensitive system information. While we’ve demonstrated enabling web access to the health endpoint only (through the use of ‘endpoints.health.web.enabled=true’) as well as enabling web access to all actuator endpoints (through the use of ‘endpoints.default.web.enabled=true’), it is wise to review the actuator security and securing endpoints reference documentation before an application is deployed to its target customer audience.

Conclusion

Spring Boot and Spring Boot Actuator offer an incredible amount of features and functionality.

Actuators, which help monitor and interact with an application, provide numerous endpoints that reveal a wealth of application information. The /health actuator endpoint, which displays information on the application’s overall health, can be used by monitoring software to alert someone if a system component becomes unavailable.

Spring Boot Actuator 2.0 includes a Neo4jHealthIndicator, automagically executing a Cypher validation statement each time /health is invoked, resulting in the seamless inclusion of Neo4j status information within the report of your application’s overall health.