Getting Started with Spring Boot Actuator

Vikram Arucharmy wrote an engaging and well-constructed post about implementing and using the spring boot actuator. For anyone creating a production application or otherwise, it's a must.

Any production application needs to be monitored for its uptime. Let’s say you’ve developed a stock market statistics application, for example, using Spring Boot for your client. This application has to be up all the time while the stock market is open. If it’s down at a crucial time, it could mean huge losses for relevant stakeholders. In addition to being monitored for uptime, an application like this would probably even need a hotline support team that can be notified immediately if the application goes down.

By using the Spring Boot Actuator as a dependency, you can enable health status indicators to monitor your application’s status without any explicit implementation. We’ll get into many of its other functionalities as well in this tutorial, along with tips on how to use it.

What is the Spring Boot Actuator?

In mechanical terms, an actuator is a mechanical device used to move or control something. Similarly, the Spring Boot Actuator can be used to monitor and manage your Spring Boot application. All the actuator features are exposed to end users using the HTTP endpoints, communication channels that allow two software programs to communicate with each other.

The Spring Boot Actuator has several production-ready features available:

• Monitoring: Checking the health status of the application to ensure that it’s running as expected without any problems. Actuator lets you check the health of the application by using the /health/ endpoint.
• Logging: Writing log messages about events that occur during the runtime of the application. Actuator helps you view log messages and configure log levels during runtime using the /loggers/ endpoint.
• Tracing: Logging all the HTTP requests to your application. It can be useful to understand how users are interacting with your application. Actuator helps you trace the HTTP requests by using the /httptrace/ endpoint.
• Metrics: Measuring the performance and managing the memory footprint of your application. Actuator provides the useful metrics of your application by using the /metrics/ endpoint.
• Auditing: Logging the authentication and authorization events of the application when Spring security is in action. This can help ensure the security and compliance of the application as well as define the lockdown mechanisms after n number of invalid login attempts. You can read more about Audit events here.

Importing and Configuring the Spring Boot Actuator

Import the Spring Boot Actuator to your Spring application, and let’s see how to enable and expose the endpoint to end users.

The spring-boot-actuator module helps you enable all the production-ready features in your Spring Boot application. Hence, you need to add this module in your dependencies. You can add the following code to the <dependencies> section of the pom.xml file, if you’re using Maven-based projects:

<dependency>  
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

If you’re using Gradle, you can use the following declaration:

dependencies { 
implementation 'org.springframework.boot:spring-boot-starter-actuator' 
}

Next, you’ll see how to enable and expose the endpoints.

Enabling Endpoints

All the available Actuator endpoints are enabled by default except the shutdown endpoint.

You can enable the Actuator endpoints using the Spring Boot Application properties file. To enable the endpoint, set the property management.endpoint.<id>.enabled in the Spring Boot properties file. The <id> must be replaced with the actual endpoint name, which needs to be enabled or disabled.

Use the below property in the properties file to enable the shutdown endpoint:

management.endpoint.shutdown.enabled=true

<id> is replaced with the endpoint name shutdown to enable the shutdown endpoint.

If you want to disable an endpoint, you can use the same property and assign the value false in place of true. This will disable the endpoint and remove the service from the application context.

If you don’t want to enable all the endpoints by default, you can disable that by using the property enabled-by-default as shown below:

management.endpoints.enabled-by-default=false

Now all the endpoints will be disabled, and you can enable each desired endpoint by setting its enabled property to true.

Exposing and Hiding Endpoints

Exposing an endpoint means making it accessible to the end users using the different technologies, namely JMX and Web (HTTP endpoints). Actuator endpoints may consist of sensitive information about the application and data. Hence, utmost care needs to be taken as to which endpoints should be exposed using which technology to make the application secure.

Similar to enabling the endpoints, you need to use the Spring Boot application.properties file to expose the endpoints. The property to expose the endpoint is management.endpoints.<technology>.exposure.include. Here technology must be replaced with either jmx or web to expose the endpoints in that specific technology.

You can find the endpoints exposed by default here. Only the enabled endpoints are exposed by default.

The property to hide the endpoint is management.endpoints.<technology>.exposure.exclude. Once again, technology must be replaced with either jmx or web to hide the endpoints in that specific technology.

A few things to note:

All the enabled endpoints are exposed in JMX by default, whereas only
health and info endpoints are exposed in Web
The exclude property takes precedence over the include property. If you have by any chance configured both exclude and include for any of the endpoints, then the endpoint will be excluded.
Now when you build your Spring Boot application, you’ll have all the relevant monitoring features readily available. You can easily consume it by using the defined endpoints.

Calling an Endpoint

In this section, you’ll learn how to call an endpoint using your browser and what will be the output of each endpoint. The following example assumes that your Spring Boot application is running in your local machine and the default port 8080. Hence the application base URL would be http://localhost:8080/.

First, you must know what endpoints are available as part of the Spring Boot Actuator in order to call it. The Spring Boot Actuator has a hypermedia (a discovery page) endpoint available under the URL <application_base_user>/actuator/ where all the available endpoints will be displayed.

To call the hypermedia endpoint /actuator/, use http://localhost:8080/actuator. You’ll see the following output with all the available endpoints displayed as a JSON text:

{
   "_links":{
      "self":{
         "href":"http://localhost:8080/actuator",
         "templated":false
      },
      "beans":{
         "href":"http://localhost:8080/actuator/beans",
         "templated":false
      },
      "caches-cache":{
         "href":"http://localhost:8080/actuator/caches/{cache}",
         "templated":true
      },
      "caches":{
         "href":"http://localhost:8080/actuator/caches",
         "templated":false
      },
      "health":{
         "href":"http://localhost:8080/actuator/health",
         "templated":false
      },
      "health-path":{
         "href":"http://localhost:8080/actuator/health/{*path}",
         "templated":true
      },
      "info":{
         "href":"http://localhost:8080/actuator/info",
         "templated":false
      },
      "conditions":{
         "href":"http://localhost:8080/actuator/conditions",
         "templated":false
      },
      "configprops":{
         "href":"http://localhost:8080/actuator/configprops",
         "templated":false
      },
      "env":{
         "href":"http://localhost:8080/actuator/env",
         "templated":false
      },
      "env-toMatch":{
         "href":"http://localhost:8080/actuator/env/{toMatch}",
         "templated":true
      },
      "loggers":{
         "href":"http://localhost:8080/actuator/loggers",
         "templated":false
      },
      "loggers-name":{
         "href":"http://localhost:8080/actuator/loggers/{name}",
         "templated":true
      },
      "heapdump":{
         "href":"http://localhost:8080/actuator/heapdump",
         "templated":false
      },
      "threaddump":{
         "href":"http://localhost:8080/actuator/threaddump",
         "templated":false
      },
      "metrics-requiredMetricName":{
         "href":"http://localhost:8080/actuator/metrics/{requiredMetricName}",
         "templated":true
      },
      "metrics":{
         "href":"http://localhost:8080/actuator/metrics",
         "templated":false
      },
      "scheduledtasks":{
         "href":"http://localhost:8080/actuator/scheduledtasks",
         "templated":false
      },
      "mappings":{
         "href":"http://localhost:8080/actuator/mappings",
         "templated":false
      }
   }
}

Next, let’s walk through the different endpoints and their defined purposes.

Health

Use the health endpoint to monitor the health of your Spring Boot application. It’ll return the current application status. This endpoint can also be used by monitoring tools to keep track of application status and notify the team when the application goes down.

This health endpoint uses the HealthContributor defined in the application context to collect the application health. When more than one HealthContirbutors is available, the final system health is derived by the StatusAggregator, which aggregates all the available health statuses from an ordered list. The first available status will be considered the overall health status.

You can check all the auto-configured HealthContributors here.

Use http://localhost:8080/actuator/health to consume the health endpoint. You’ll see the following JSON output:

{"status":"UP","groups":["custom"]}

Let’s break that down:

• status: Provides the status of application.
• UP: The application is running fine.
• groups: Provides the name of the group to which this status is assigned. Groups organize different health indicators.
• custom: The current health status’s group.

Metrics

Metrics can be used to measure the performance of your production application. Spring Boot Actuator supports dependency management and auto configuration for the Micrometer, a metrics façade that supports most popular monitoring systems.

To know all the available metrics in your Spring boot application, use http://localhost:8080/actuator/metrics. You’ll see all the available metrics names as given:

{
   "names":[
      "http.server.requests",
      "jvm.buffer.count",
      "jvm.buffer.memory.used",
      "jvm.buffer.total.capacity",
      "jvm.classes.loaded",
      "jvm.classes.unloaded",
      "jvm.gc.live.data.size",
      "jvm.gc.max.data.size",
      "jvm.gc.memory.allocated",
      "jvm.gc.memory.promoted",
      "jvm.gc.pause",
      "jvm.memory.committed",
      "jvm.memory.max",
      "jvm.memory.used",
      "jvm.threads.daemon",
      "jvm.threads.live",
      "jvm.threads.peak",
      "jvm.threads.states",
      "logback.events",
      "process.cpu.usage",
      "process.start.time",
      "process.uptime",
      "system.cpu.count",
      "system.cpu.usage",
      "tomcat.sessions.active.current",
      "tomcat.sessions.active.max",
      "tomcat.sessions.alive.max",
      "tomcat.sessions.created",
      "tomcat.sessions.expired",
      "tomcat.sessions.rejected"
   ]
}

Now, you’ll learn how to consume a specific metric from the available metrics. Let’s take http.server.requests and jvm.memory.used metrics as an example.

http.server.requests returns the number of http server requests processed by the application. Use http://localhost:8080/actuator/metrics/http.server.requests to find out the number of http requests. You’ll see the following output:

{
   "name":"http.server.requests",
   "description":null,
   "baseUnit":"seconds",
   "measurements":[
      {
         "statistic":"COUNT",
         "value":19.0
      },
      {
         "statistic":"TOTAL_TIME",
         "value":1.923151205
      },
      {
         "statistic":"MAX",
         "value":0.0
      }
   ],
   "availableTags":[
      {
         "tag":"exception",
         "values":[
            "None",
            "ResponseStatusException"
         ]
      },
      {
         "tag":"method",
         "values":[
            "GET"
         ]
      },
      {
         "tag":"uri",
         "values":[
            "/actuator/metrics/{requiredMetricName}",
            "/employees/{id}",
            "/employees",
            "NOT_FOUND",
            "/actuator/health",
            "/actuator/health/{*path}",
            "/actuator/metrics"
         ]
      },
      {
         "tag":"outcome",
         "values":[
            "CLIENT_ERROR",
            "SUCCESS"
         ]
      },
      {
         "tag":"status",
         "values":[
            "404",
            "200"
         ]
      }
   ]
}

COUNT shows the number of HTTP requests handled by your application and TOTAL_TIME shows the total time taken to process them.

jvm.memory.used returns the used memory metric of your application. Use http://localhost:8080/actuator/metrics/jvm.memory.used to find the used memory. You’ll see the following output:

{
   "name":"jvm.memory.used",
   "description":"The amount of used memory",
   "baseUnit":"bytes",
   "measurements":[
      {
         "statistic":"VALUE",
         "value":5.6238416E7
      }
   ],
   "availableTags":[
      {
         "tag":"area",
         "values":[
            "heap",
            "nonheap"
         ]
      },
      {
         "tag":"id",
         "values":[
            "Survivor Space",
            "Eden Space",
            "Metaspace",
            "Code Cache",
            "Tenured Gen"
         ]
      }
   ]
} 

VALUE shows the value of the JVM memory used by your Spring boot application in Bytes.

You can explore all the available metrics by appending the metric name in the URL http://localhost:8080/actuator/metrics/ to find the different useful metrics of your application.

Conclusion

For any business-critical application, monitoring, tracing, logging, and auditing are crucial to ensure uptime and that the application is consumed appropriately by users. With Spring Boot Actuator, you can enable these functionalities in your application in a matter of minutes, simply by adding it as a dependency in your Maven POM file.