{"id":15178802,"url":"https://github.com/andrecaiado/spring-boot-actuator","last_synced_at":"2026-01-23T06:20:01.585Z","repository":{"id":253147393,"uuid":"842551421","full_name":"andrecaiado/spring-boot-actuator","owner":"andrecaiado","description":"Spring Boot application with actuator configuration and integration with external monitoring systems","archived":false,"fork":false,"pushed_at":"2024-08-19T10:14:44.000Z","size":196,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-14T05:24:23.158Z","etag":null,"topics":["actuator","docker","dockercompose","grafana","prometheus","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrecaiado.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-14T15:23:53.000Z","updated_at":"2024-08-19T14:27:46.000Z","dependencies_parsed_at":"2024-09-23T10:30:42.749Z","dependency_job_id":"baa86934-44b0-4d5a-913d-cfd8b3acea6b","html_url":"https://github.com/andrecaiado/spring-boot-actuator","commit_stats":{"total_commits":11,"total_committers":2,"mean_commits":5.5,"dds":0.2727272727272727,"last_synced_commit":"0e2dde6af414ec00ec3e9f7422cd426a6b38229c"},"previous_names":["andrecaiado/spring-boot-actuator"],"tags_count":0,"template":false,"template_full_name":"andrecaiado/spring-boot-template","purl":"pkg:github/andrecaiado/spring-boot-actuator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecaiado%2Fspring-boot-actuator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecaiado%2Fspring-boot-actuator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecaiado%2Fspring-boot-actuator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecaiado%2Fspring-boot-actuator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrecaiado","download_url":"https://codeload.github.com/andrecaiado/spring-boot-actuator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrecaiado%2Fspring-boot-actuator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28682259,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T05:48:07.525Z","status":"ssl_error","status_checked_at":"2026-01-23T05:48:07.129Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actuator","docker","dockercompose","grafana","prometheus","spring-boot"],"created_at":"2024-09-27T15:23:17.984Z","updated_at":"2026-01-23T06:20:01.560Z","avatar_url":"https://github.com/andrecaiado.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spring Boot Actuator project\n\nSpring Boot application with Actuator configuration and integration with external monitoring systems (Prometheus and Grafana).\n\nThis 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](https://github.com/andrecaiado/spring-boot-template). \n\n# Contents\n\n- [Getting Started](#getting-started)\n  - [Main features](#main-features)\n  - [Dependencies and requirements](#dependencies-and-requirements)\n  - [Run the project](#run-the-project)\n- [Exposing Actuator Endpoints](#exposing-actuator-endpoints)\n- [Info Endpoint](#info-endpoint)\n- [Health Endpoint](#health-endpoint)\n- [Metrics Endpoints](#metrics-endpoints)\n  - [Custom Metrics](#custom-metrics)\n- [Securing Actuator Endpoints with Spring Security](#securing-actuator-endpoints-with-spring-security)\n- [Monitoring Systems Integration](#monitoring-systems-integration)\n  - [Prometheus](#prometheus)\n    - [Integration with the Spring Boot application](#integration-with-the-spring-boot-application)\n    - [Prometheus server](#prometheus-server)\n  - [Grafana](#grafana)\n    - [Setting up the Prometheus data source in Grafana](#setting-up-the-prometheus-data-source-in-grafana)\n    - [Importing a Grafana dashboard](#importing-a-grafana-dashboard)\n\n# Getting Started\n\nThis 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.\n\n## Main features\n\nThe main features of this project are:\n- Configures Spring Boot Actuator to expose endpoints over HTTP\n- Implements a custom metric for example purposes\n- Docker compose configuration to launch external services (Postgres, Prometheus, Grafana)\n- Integrates the application with Prometheus monitoring system to collect metrics\n- Demonstrates how to connect Grafana with Prometheus to visualize metrics (including importing a pre-built dashboard)\n- Spring Security configuration to secure sensitive actuator endpoints\n\n## Dependencies and requirements\n\nThe following dependency are required to implement this project features:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\n    \u003cartifactId\u003espring-boot-starter-actuator\u003c/artifactId\u003e\n\u003c/dependency\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\n    \u003cartifactId\u003espring-boot-starter-security\u003c/artifactId\u003e\n\u003c/dependency\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.micrometer\u003c/groupId\u003e\n    \u003cartifactId\u003emicrometer-registry-prometheus\u003c/artifactId\u003e\n\u003c/dependency\u003e\n```\n\nTo launch and run the external services (Postgres, Prometheus and Grafana) in Docker containers, the following requirements are needed:\n\n- [Docker](https://docs.docker.com/get-docker/)\n- [Docker Compose](https://docs.docker.com/compose/install/)\n\nTo run the project, the requirements are:\n\n- [Java 17 (or higher)](https://www.oracle.com/java/technologies/javase-jdk17-downloads.html)\n- [Maven](https://maven.apache.org/download.cgi)\n\n## Run the project\n\nTo run the project, follow the steps below.\n\n```shell\nmvn spring-boot:run\n```\n\nThe application will be available at [http://localhost:8080](http://localhost:8080).\n\nThe external services (Postgres, Prometheus, and Grafana) configured in the [docker-compose.yaml](docker-compose.yaml) file will automatically be launched due to the `spring-boot-docker-compose` dependency.\n\nIn any case, the external services can also be launched manually by running on of the following command:\n\n```shell\n# Start all the external services\ndocker compose up -d\n```\n\n```shell\n# Start a specific external service \ndocker compose up -d \u003cservice-name\u003e\n# Replace \u003cservice-name\u003e with the service you want to start (prometheus, grafana or postgres)\n```\n\n# Exposing Actuator Endpoints\n\nThe actuators endpoints are available at [http://localhost:8080/actuator](http://localhost:8080/actuator). \n\nBy 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.\n\n```yaml\nmanagement:\n  endpoints:\n    web:\n      exposure:\n        include: \"*\" # Expose all endpoints\n```\nThe shutdown endpoint is not exposed because it is not enabled (it is disabled by default). \n\n# Enabling the Shutdown Endpoint\n\nThe shutdown endpoint is used to shutdown the application and so, it is disabled by default. \nTo enable this endpoint, the following configuration must be added to the `application.yaml` file.\n\n```yaml\nmanagement:\n  endpoint:\n    shutdown:\n      enabled: true\n```\n\n# Info Endpoint\n\nThe `info` endpoint is available at http://localhost:8080/actuator/info and is used to display information about the application. \n\nThe information to be displayed must be added to the `application.yaml`.\n\n```yaml\ninfo:\n  app:\n    name: @project.name@\n    description: @project.description@\n    version: @project.version@\n    encoding: @project.build.sourceEncoding@\n    java:\n      version: @java.version@\n```\n\nWe also have to add the following property to the `application.yaml` so the info contents are displayed in the actuator `info` endpoint.\n\n```yaml\nmanagement:\n  info:\n    env:\n      enabled: true\n```\n\n# Health Endpoint\n\nBy default, the health endpoint only returns the status of the application. The status can be `UP`, `DOWN`, or `UNKNOWN`.\n\n```json\n{\n    \"status\": \"UP\"\n}\n```\nIf we want to see more details about the application health, we can add the following configuration to the `application.yaml` file.\n\n```yaml\nmanagement:\n  endpoint:\n    health:\n      show-details: always\n```\n\nNow, 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.\n\n```json\n{\n  \"status\": \"UP\",\n  \"components\": {\n    \"db\": {\n      \"status\": \"UP\",\n      \"details\": {\n        \"database\": \"PostgreSQL\",\n        \"validationQuery\": \"isValid()\"\n      }\n    },\n    \"diskSpace\": {\n      \"status\": \"UP\",\n      \"details\": {\n        \"total\": 494384795648,\n        \"free\": 422728798208,\n        \"threshold\": 10485760,\n        \"path\": \"/Users/a.caiadodasilva/code/training/spring-boot-actuator/.\",\n        \"exists\": true\n      }\n    },\n    \"ping\": {\n      \"status\": \"UP\"\n    }\n  }\n}\n```\n\n# Metrics Endpoints\n\nThe metrics endpoint provides information about the application performance. The metrics are divided into three categories: `system`, `jvm`, and `process`.\n\nThe metrics endpoint is available at [http://localhost:8080/actuator/metrics](http://localhost:8080/actuator/metrics).\n\n## Custom Metrics\n\nWe can create custom metrics to monitor specific parts of the application.\n\nTo learn more about metric types, please refer to the [Prometheus Metric Types page](https://prometheus.io/docs/concepts/metric_types/).\n\nIn 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.\n\n```java\n@Service\n@Slf4j\npublic class EmployeeService {\n\n    private final EmployeeRepository employeeRepository;\n\n    private final MeterRegistry meterRegistry;\n\n    public EmployeeService(EmployeeRepository employeeRepository, MeterRegistry meterRegistry) {\n        this.employeeRepository = employeeRepository;\n        this.meterRegistry = meterRegistry;\n\n        Gauge.builder(\"employees_count\", employeeRepository::count)\n                .description(\"The current number of employees in the database\")\n                .register(meterRegistry);\n    }\n    ...\n}\n```\n\nThis metric will be available at [http://localhost:8080/actuator/metrics/employees_count](http://localhost:8080/actuator/metrics/employees_count).\n\n```json\n{\n  \"name\": \"employees_count\",\n  \"description\": \"The current number of employees in the database\",\n  \"measurements\": [\n    {\n      \"statistic\": \"VALUE\",\n      \"value\": 20\n    }\n  ],\n  \"availableTags\": []\n}\n```\n\n# Securing Actuator Endpoints with Spring Security\n\nTo secure the actuator endpoints, we can use Spring Security.\n\nThe following dependency was added to enable Spring Security in the Spring Boot application.\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\n    \u003cartifactId\u003espring-boot-starter-security\u003c/artifactId\u003e\n\u003c/dependency\u003e\n```\n\nA configuration was added to secure the `shutdown` actuator endpoint with HTTP Basic Authentication.\n\nThe configuration also includes an inMemory user with credentials to access the `shutdown` endpoint.\n\nThe configuration can be found in the [SecurityConfig.java](src%2Fmain%2Fjava%2Fcom%2Fexample%2Fspringboottemplate%2Fconfig%2FSecurityConfig.java) class.\n\n# Monitoring Systems Integration\n\nThe Spring Boot application was integrated with two monitoring systems: Prometheus and Grafana.\n\n## Prometheus\n\nPrometheus 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.\n\n### Integration with the Spring Boot application\n\nThe Prometheus monitoring system was integrated with the Spring Boot application to collect metrics from the application.\n\nTo 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](https://micrometer.io/docs).\n\nThe following dependency was added to the `pom.xml` file.\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.micrometer\u003c/groupId\u003e\n    \u003cartifactId\u003emicrometer-registry-prometheus\u003c/artifactId\u003e\n\u003c/dependency\u003e\n```\n\nAfter 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.\n\nThe metrics can then be accessed at [http://localhost:8080/actuator/prometheus](http://localhost:8080/actuator/prometheus).\n\n### Prometheus server\n\nA Prometheus server service was added to the `docker-compose.yml` file to start the Prometheus server in a Docker container.  \n\nThe configuration for the Prometheus server can be found in the [prometheus.yml](prometheus.yml) file.\n\nTo start the Prometheus server, run the following command:\n\n```shell\ndocker compose up -d prometheus\n```\n\nThe Prometheus server will be available at [http://localhost:9090](http://localhost:9090).\n\n## Grafana\n\nGrafana is an open-source monitoring and observability platform that allows users to visualize metrics collected by Prometheus.\n\nAlthough Prometheus provides dashboards to visualize the metrics, Grafana is a more powerful tool for this purpose.\n\nA Grafana server service was added to the `docker-compose.yml` file to start the Grafana server in a Docker container.\n\nTo start the Grafana server, run the following command:\n\n```shell\ndocker compose up -d grafana\n```\n\nThe Grafana server will be available at [http://localhost:3000](http://localhost:3000).\n\nThe default credentials to access Grafana are:\n\n- Username: admin\n- Password: admin\n\nChange the password after the first login or skip the password change by clicking on the `Skip` button.\n\n### Setting up the Prometheus data source in Grafana\n\nAfter logging in, add a new data source to Grafana:\n- Data Source type: Prometheus\n- Prometheus server URL: http://localhost:9090 \n  - It will probably not work since we are running the services in Docker containers. Use `host.docker.internal` instead of `localhost`.\n- Authentication: None\n- Click \"Save \u0026 Test\"\n\n### Importing a Grafana dashboard\n\nInstead of creating a new dashboard from scratch, we can import a pre-built dashboard from the Grafana dashboard library.\n\nVisit the [Grafana dashboard library](https://grafana.com/grafana/dashboards) and search for a dashboard that fits your needs.\n\nTo learn about Importing Grafana dashboards, please refer to the [Grafana dashboards documentation](https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/import-dashboards/).\n\n**Example of an imported dashboard applied on this project:**\n\nSource: [Spring Boot Statistics \u0026 Endpoint Metrics](https://grafana.com/grafana/dashboards/14430-spring-boot-statistics-endpoint-metrics/)\n\n![grafana-dashboard.png](src%2Fmain%2Fresources%2Fgrafana-dashboard.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrecaiado%2Fspring-boot-actuator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrecaiado%2Fspring-boot-actuator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrecaiado%2Fspring-boot-actuator/lists"}