Spring actuator

The Spring Boot Actuator provides a set of utilities related to the uptime and status of your application. With the Actuator, you can obtain reports on the health and metrics of your application. This information will help you with maintaining your application, keeping it running as efficiently as possible, and understanding what could be wrong.

Setting up the actuator

You can add the actuator to your Gradle project through Gradle dependencies. This can be done by adding the following dependency to your Gradle configuration.

implementation 'org.springframework.boot:spring-boot-starter-actuator'

implementation("org.springframework.boot:spring-boot-starter-actuator")

Once this dependency is added, you can verify that it is running by compiling the project and navigating to the /actuator path. If your web server port is 8080, the full path will be http://localhost:8080/actuator.

If the actuator has been successfully set up, you should see a JSON output similar to the one below. You can just open the link in your browser or any other tool that can send a GET request.

{
  "_links": {
    "self": {
      "href": "http://localhost:8080/actuator",
      "templated": false
    },
    "health-path": {
      "href": "http://localhost:8080/actuator/health/{*path}",
      "templated": true
    },
    "health": {
      "href": "http://localhost:8080/actuator/health",
      "templated": false
    }
  }
}

This JSON output is showing how the actuator is currently configured for our application. Each of the href values represents a path that is implemented. By default, there are three paths enabled, /actuator, /actuator/health/{*path} and /actuator/health.

The health-related path, /actuator/health, can help you determine if your app is healthy. It can return UP if the application is healthy, DOWN if there is something wrong, OUT_OF_SERVICE if the service is deliberately shut down, or UNKNOWN if the status is not known. To view the status, simply navigate to the /actuator/health path to see the result, similar to the one shown below.

{"status":"UP"}

Configuring endpoints in actuators

To apply modifications to the endpoints available through the actuator, you can modify the application.properties file located at src\main\resources. To modify what paths are available through the actuator, you can modify the management.endpoints.web.exposure.include property. The example below shows how to expose only the health endpoint:

management.endpoints.web.exposure.include=health

Similarly, it is possible to add new endpoints into the actuator.

In the list of available endpoints you can find JMX endpoints, which can provide valuable information about the metrics for our application.

To expose these JMX endpoints, you can use the management.endpoints.jmx.exposure.include property in the application.properties file. For example, the properties below enable the metrics and info components for JMX:

management.endpoints.jmx.exposure.include=metrics,info

To expose all endpoints, you can use the * character with the include. For example, management.endpoints.web.exposure.include=* would expose all web endpoints. These additional endpoints give us a number of valuable tools for analyzing our application. For instance, the metrics endpoint is useful for analyzing how your application system is running. You can access the /actuator/metrics endpoint to view the available application metrics.

{
  "names": [
    "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.files.max",
    "process.files.open",
    "process.start.time",
    "process.uptime",
    "system.cpu.count",
    "system.cpu.usage",
    "system.load.average.1m",
    "tomcat.sessions.active.current",
    "tomcat.sessions.active.max",
    "tomcat.sessions.alive.max",
    "tomcat.sessions.created",
    "tomcat.sessions.expired",
    "tomcat.sessions.rejected"
  ]
}

You can easily access any of these metrics by referencing them in the path. For example, /actuator/metrics/jvm.buffer.memory.used will display the metrics related to the buffer memory used by the JVM of the application.

{
  "name": "jvm.buffer.memory.used",
  "description": "An estimate of the memory that the Java virtual machine is using for this buffer pool",
  "baseUnit": "bytes",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 24576
    }
  ],
  "availableTags": [
    {
      "tag": "id",
      "values": [
        "direct",
        "mapped"
      ]
    }
  ]
}

It is also possible to define custom metrics through the actuator. These custom metrics utilize a class called MeterRegistry, which allows us to implement various meters to measure metrics in our application. By default, the MeterRegistry provides us with the following meters:

• Counter reports a count of a specific metric in the application. For example, you can count how many times someone visits an endpoint.
• Gauge shows a value from a meter. For example, you can measure the amount of memory consumed by an endpoint.
• Timers measure latencies or frequencies. For example, you can time how long it takes to return a result from an endpoint.
• DistributionSummary provides the distribution of events. For example, you can measure how often someone visits one endpoint compared to another user.

These meters will allow you to customize your metrics in better, more specific ways to serve your application.

Actuator endpoint security

Since the endpoints are exposed and contain valuable information, it is essential to ensure they are properly secured from unauthorized access. Starting in Spring Boot 2.0, you can add Spring Security in order to automatically secure actuator endpoints in your project. If you want to create additional configurations for your actuator endpoints, it is possible to do so by overriding the configure method to create specific requirements for the endpoints. For example, the code below shows how to set the configuration to authorize requests that match the /actuator/** path:

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
            .antMatchers("/actuator/**").hasAuthority("MONITORING")
            .anyRequest().authenticated();
}

override fun configure(http: HttpSecurity) {
    http.authorizeRequests()
        .antMatchers("/actuator/**").hasAuthority("MONITORING")
        .anyRequest().authenticated()
}

It is also possible to make adjustments to endpoints through the application.properties configuration. For instance, the following configuration will make the health endpoint show details only when it is accessed by a properly authorized user.

management.endpoint.health.show-details=when_authorized

These features will allow you to fully secure your actuator endpoints from unauthorized access.

Conclusion

In this topic, you have learned how actuators provide details about application status and health. Using the metrics and reports provided by the actuator, it is possible to check if your Spring applications are operating correctly. It allows you to quickly identify if there is a downtime in the application, as well as its possible causes. It is also important to remember that when you set up actuators, you should add proper endpoint security to ensure that endpoints don't leak sensitive data.