Spring Boot Actuator project

Spring Boot application with Actuator configuration and integration with external monitoring systems (Prometheus and Grafana).

This README file will focus on the actuator features implementation. For more information about the other project features, please refer to the project template: spring-boot-template.

Getting Started
Exposing Actuator Endpoints
Info Endpoint
Health Endpoint
Metrics Endpoints
- Custom Metrics
Securing Actuator Endpoints with Spring Security
Monitoring Systems Integration
- Prometheus
  - Integration with the Spring Boot application
  - Prometheus server
- Grafana
  - Setting up the Prometheus data source in Grafana
  - Importing a Grafana dashboard

Getting Started

This section provides an overview of the main features, necessary dependencies, and step-by-step instructions to help you get the application up and running quickly.

Main features

The main features of this project are:

Configures Spring Boot Actuator to expose endpoints over HTTP
Implements a custom metric for example purposes
Docker compose configuration to launch external services (Postgres, Prometheus, Grafana)
Integrates the application with Prometheus monitoring system to collect metrics
Demonstrates how to connect Grafana with Prometheus to visualize metrics (including importing a pre-built dashboard)
Spring Security configuration to secure sensitive actuator endpoints

Dependencies and requirements

The following dependency are required to implement this project features:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

To launch and run the external services (Postgres, Prometheus and Grafana) in Docker containers, the following requirements are needed:

To run the project, the requirements are:

Run the project

To run the project, follow the steps below.

mvn spring-boot:run

The application will be available at http://localhost:8080.

The external services (Postgres, Prometheus, and Grafana) configured in the docker-compose.yaml file will automatically be launched due to the spring-boot-docker-compose dependency.

In any case, the external services can also be launched manually by running on of the following command:

# Start all the external services
docker compose up -d

# Start a specific external service 
docker compose up -d <service-name>
# Replace <service-name> with the service you want to start (prometheus, grafana or postgres)

Exposing Actuator Endpoints

The actuators endpoints are available at http://localhost:8080/actuator.

By default, only the health and info endpoints are exposed over HTTP. To expose all the endpoints, the following configuration was added to the application.yaml file.

management:
  endpoints:
    web:
      exposure:
        include: "*" # Expose all endpoints

The shutdown endpoint is not exposed because it is not enabled (it is disabled by default).

Enabling the Shutdown Endpoint

The shutdown endpoint is used to shutdown the application and so, it is disabled by default. To enable this endpoint, the following configuration must be added to the application.yaml file.

management:
  endpoint:
    shutdown:
      enabled: true

Info Endpoint

The info endpoint is available at http://localhost:8080/actuator/info and is used to display information about the application.

The information to be displayed must be added to the application.yaml.

info:
  app:
    name: @project.name@
    description: @project.description@
    version: @project.version@
    encoding: @project.build.sourceEncoding@
    java:
      version: @java.version@

We also have to add the following property to the application.yaml so the info contents are displayed in the actuator info endpoint.

management:
  info:
    env:
      enabled: true

Health Endpoint

By default, the health endpoint only returns the status of the application. The status can be UP, DOWN, or UNKNOWN.

{
    "status": "UP"
}

If we want to see more details about the application health, we can add the following configuration to the application.yaml file.

management:
  endpoint:
    health:
      show-details: always

Now, the health endpoint will return more details about the application health. Because we have a PostgreSQL database configured in the application, the health endpoint will return the status of the database connection.

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "PostgreSQL",
        "validationQuery": "isValid()"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 494384795648,
        "free": 422728798208,
        "threshold": 10485760,
        "path": "/Users/a.caiadodasilva/code/training/spring-boot-actuator/.",
        "exists": true
      }
    },
    "ping": {
      "status": "UP"
    }
  }
}

Metrics Endpoints

The metrics endpoint provides information about the application performance. The metrics are divided into three categories: system, jvm, and process.

The metrics endpoint is available at http://localhost:8080/actuator/metrics.

Custom Metrics

We can create custom metrics to monitor specific parts of the application.

To learn more about metric types, please refer to the Prometheus Metric Types page.

In this project, we created a custom gauge metric to monitor the number of employees in the database. This metric was implemented in the EmployeeService class as shown below.

@Service
@Slf4j
public class EmployeeService {

    private final EmployeeRepository employeeRepository;

    private final MeterRegistry meterRegistry;

    public EmployeeService(EmployeeRepository employeeRepository, MeterRegistry meterRegistry) {
        this.employeeRepository = employeeRepository;
        this.meterRegistry = meterRegistry;

        Gauge.builder("employees_count", employeeRepository::count)
                .description("The current number of employees in the database")
                .register(meterRegistry);
    }
    ...
}

This metric will be available at http://localhost:8080/actuator/metrics/employees_count.

{
  "name": "employees_count",
  "description": "The current number of employees in the database",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 20
    }
  ],
  "availableTags": []
}

Securing Actuator Endpoints with Spring Security

To secure the actuator endpoints, we can use Spring Security.

The following dependency was added to enable Spring Security in the Spring Boot application.

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

A configuration was added to secure the shutdown actuator endpoint with HTTP Basic Authentication.

The configuration also includes an inMemory user with credentials to access the shutdown endpoint.

The configuration can be found in the SecurityConfig.java class.

Monitoring Systems Integration

The Spring Boot application was integrated with two monitoring systems: Prometheus and Grafana.

Prometheus

Prometheus is an open-source monitoring system that collects metrics from the application and stores them in a time-series data, i.e. metrics information is stored with the timestamp at which it was recorded, alongside optional key-value pairs called labels.

Integration with the Spring Boot application

The Prometheus monitoring system was integrated with the Spring Boot application to collect metrics from the application.

To integrate Prometheus with the Spring Boot application, we used the micrometer-registry-prometheus dependency. To learn more about Micrometer, please refer to the Micrometer documentation.

The following dependency was added to the pom.xml file.

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

After adding the dependency, Spring Boot will automatically configure a PrometheusMeterRegistry and a CollectorRegistry to collect and export metrics in a format that can be scraped by Prometheus.

The metrics can then be accessed at http://localhost:8080/actuator/prometheus.

Prometheus server

A Prometheus server service was added to the docker-compose.yml file to start the Prometheus server in a Docker container.

The configuration for the Prometheus server can be found in the prometheus.yml file.

To start the Prometheus server, run the following command:

docker compose up -d prometheus

The Prometheus server will be available at http://localhost:9090.

Grafana

Grafana is an open-source monitoring and observability platform that allows users to visualize metrics collected by Prometheus.

Although Prometheus provides dashboards to visualize the metrics, Grafana is a more powerful tool for this purpose.

A Grafana server service was added to the docker-compose.yml file to start the Grafana server in a Docker container.

To start the Grafana server, run the following command:

docker compose up -d grafana

The Grafana server will be available at http://localhost:3000.

The default credentials to access Grafana are:

Username: admin
Password: admin

Change the password after the first login or skip the password change by clicking on the Skip button.

Setting up the Prometheus data source in Grafana

After logging in, add a new data source to Grafana:

Data Source type: Prometheus
Prometheus server URL: http://localhost:9090
- It will probably not work since we are running the services in Docker containers. Use host.docker.internal instead of localhost.
Authentication: None
Click "Save & Test"