Getting Started with Spring Boot Actuator
Tags: tutorial, programming
Published: 2021-04-22 13:16:11

Vikram Arucharmy wrote an engaging and well-constructed post about implementing and using the [spring boot actuator](https://lightrun.com/best-practices/getting-started-with-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](https://spring.io/projects/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.

![spring boot logo](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s8i89vnaae703sgv2d3x.jpg)

**By using the [Spring Boot Actuator](https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html) 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](https://searchapparchitecture.techtarget.com/definition/API-endpoint), 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](https://lightrun.com/debugging/debugging-microservices-the-ultimate-guide/) 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](https://lightrun.com/best-practices/how-to-understand-log-levels/) 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](https://www.baeldung.com/spring-boot-authentication-audit).

![spring boot modules](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/s0ylhkrbolcwmm0k8elw.png)

## 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](https://maven.apache.org/) projects:
```
<dependency>  
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
```
If you’re using [Gradle](https://gradle.org/), 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](https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-endpoints) are enabled by default except the shutdown endpoint.

You can enable the Actuator endpoints using the [Spring Boot Application](https://www.tutorialspoint.com/spring_boot/spring_boot_application_properties.htm) 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](https://docs.spring.io/spring-framework/docs/3.2.x/spring-framework-reference/html/jmx.html) 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](https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-endpoints-exposing-endpoints). 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](https://github.com/spring-projects/spring-boot/tree/v2.4.3/spring-boot-project/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/health/HealthContributor.java) 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](https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-health-indicators) 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](https://micrometer.io/), a metrics façade that supports most [popular monitoring systems](https://micrometer.io/docs).

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](https://spring.io/guides/gs/actuator-service/), 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.