15.2.1 Fetching essential application information

At the beginning of a typical visit to the doctor, we’re usually asked two very basic questions: who are you and how do you feel? Although the words chosen by the doctor or nurse may be different, they ultimately want to know a little bit about the person they’re treating and why you’re seeing them.

Those same essential questions are what Actuator’s /info and /health endpoints answer for a Spring Boot application. The /info endpoint tells you a little about the application, and the /health endpoint tells you how healthy the application is.

ASKING FOR INFORMATION ABOUT AN APPLICATION

To learn a little bit of information about a running Spring Boot application, you can ask the /info endpoint. By default, however, the /info endpoint isn’t very informative. Here’s what you might see when you make a request for it using curl:

$ curl localhost:8081/actuator/info
{}

Although it may seem that the /info endpoint isn’t very useful, it’s best to think of it as a clean canvas on which you may paint any information you’d like to present.

We have several ways to supply information for the /info endpoint to return, but the most straightforward way is to create one or more configuration properties where the property name is prefixed with info. For example, suppose that you want the response from the /info endpoint to include support contact information, including an email address and phone number. To do that, you can configure the following properties in the application.yml file:

info:
  contact:
    email: support@tacocloud.com
    phone: 822-625-6831

Neither the info.contact.email property nor the info.contact.phone property has any special meaning to Spring Boot or any bean that may be in the application context. However, by virtue of the fact that it’s prefixed with info, the /info endpoint will now echo the value of the property in its response as follows:

{
  "contact": {
    "email": "support@tacocloud.com",
    "phone": "822-625-6831"
  }
}

In section 15.3.1, we’ll look at a few other ways to populate the /info endpoint with useful information about an application.

INSPECTING APPLICATION HEALTH

Issuing an HTTP GET request for the /health endpoint results in a simple JSON response with the health status of your application. For example, here’s what you might see when using curl to fetch the /health endpoint:

$ curl localhost:8080/actuator/health
{"status":"UP"}

You may be wondering how useful it is to have an endpoint that reports that the application is UP. What would it report if the application were down?

As it turns out, the status shown here is an aggregate status of one or more health indicators. Health indicators report the health of external systems that the application interacts with, such as databases, message brokers, and even Spring Cloud components such as Eureka and the Config Server. The health status of each indicator could be one of the following:

• UP - The external system is up and is reachable.
• DOWN - The external system is down or unreachable.
• UNKNOWN - The status of the external system is unclear.
• OUT\_OF\_SERVICE - The external system is reachable but is currently unavailable.

The health statuses of all health indicators are then aggregated into the application’s overall health status, applying the following rules:

• If all health indicators are UP, then the application health status is UP.
• If one or more health indicators are DOWN, then the application health status is DOWN.
• If one or more health indicators are OUT\_OF\_SERVICE, then the application health status is OUT\_OF\_SERVICE.
• UNKNOWN health statuses are ignored and aren’t rolled into the application’s aggregate health.

By default, only the aggregate status is returned in response to a request for /health. You can configure the management.endpoint.health.show-details property, however, to show the full details of all health indicators, as shown next:

management:
  endpoint:
    health:
      show-details: always

The management.endpoint.health.show-details property defaults to never, but it can also be set to always to always show the full details of all health indicators, or to when-authorized to show the full details only when the requesting client is fully authorized.

Now when you issue a GET request to the /health endpoint, you get full health indicator details. Here’s a sample of what that might look like for a service that integrates with the Mongo document database:

{
    "status": "UP",
    "details": {
        "mongo": {
            "status": "UP",
            "details": {
                "version": "3.2.2"
            }
        },
        "diskSpace": {
            "status": "UP",
            "details": {
                "total": 499963170816,
                "free": 177284784128,
                "threshold": 10485760
            }
        }
    }
}

All applications, regardless of any other external dependencies, will have a health indicator for the filesystem named diskSpace. The diskSpace health indicator indicates the health of the filesystem (hopefully, UP), which is determined by how much free space is remaining. If the available disk space drops below the threshold, it will report a status of DOWN.

In the preceding example, there’s also a mongo health indicator, which reports the status of the Mongo database. Details shown include the Mongo database version.

Autoconfiguration ensures that only health indicators that are pertinent to an application will appear in the response from the /health endpoint. In addition to the mongo and diskSpace health indicators, Spring Boot also provides health indicators for several other external databases and systems, including the following:

• Cassandra
• Config Server
• Couchbase
• Eureka
• Hystrix
• JDBC data sources
• Elasticsearch
• InfluxDB
• JMS message brokers
• LDAP
• Email servers
• Neo4j
• Rabbit message brokers
• Redis
• Solr

Additionally, third-party libraries may contribute their own health indicators. We’ll look at how to write a custom health indicator in section 15.3.2.

As you’ve seen, the /health and /info endpoints provide general information about the running application. Meanwhile, other Actuator endpoints provide insight into the application configuration. Let’s look at how Actuator can show how an application is configured.