Spring Boot - Actuator

Posted on In

Spring Boot Actuator provides metrics and app monitoring to our application.

Dependency

add spring-boot-starter-actuator dependency. 

1
2
3
4
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

If you are creating a web application, you need spring-boot-starter-web dependency

1
2
3
4
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Endpoints

Start from Spring Boot 2.x, most endpoints are disabled by default. Only /health and /info are enabled.

To allow all the endpoints, set management.endpoints.web.exposure.include property to *

1
2
management.endpoints.web.exposure.include=*

we can also enable specific endpoints, for example: 

1
management.endpoints.web.exposure.include=beans, metrics

Here are all the endpoint

  • /auditevents - provides information about the application’s audit events. Audit events are login or logout events.
  • /beans - provides information about the application’s beans.
  • /conditions - provides information about the evaluation of conditions on configuration and auto-configuration classes.
  • /configprops - provides information about the application’s @ConfigurationProperties beans.
  • /env - provides information about the application’s Environment.
  • /flyway - provides information about database migrations performed by Flyway.
  • /health - provides detailed information about the health of the application.
  • /heapdump - provides a heap dump from the application’s JVM.
  • /httptrace - provides information about HTTP request-response exchanges.
  • /info - provides general information about the application.
  • /liquibase - provides information about database change sets applied by Liquibase.
  • /logfile - provides access to the contents of the application’s log file.
  • /mappings - provides information about the application’s request mappings.
  • /metrics - provides access to application metrics.
  • /prometheus - provides Spring Boot application’s metrics in the format required for scraping by a Prometheus server.
  • /scheduledtasks - provides information about the application’s scheduled tasks.
  • /sessions - provides information about the application’s HTTP sessions that are managed by Spring Session.
  • /shutdown - to gracefully shut down the application. Need to use Http POST method for this endpoint.
  • /threaddump - provides a thread dump from the application’s JVM.

Actuator Endpoint

http://localhost:8080/actuator/ - The /actuator endpoint list all the available actuator endpoints avaialble.

sample response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "_links":
    {
      "self": { "href": "http://localhost:8080/actuator", "templated": false },
      "beans":
        { "href": "http://localhost:8080/actuator/beans", "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,
        },
}

Health Endpoint

http://localhost:8080/actuator/health - The health endpoint provides detailed information about the health of the application.

sample response

1
2
3
{
    "status" : "UP"
}

Health Indicator

You can create customized Health Indicator

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
@Component
public class ServicesHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        String service1Health = checkService1Health();
        String service2Health = checkService2Health();

        Map<String, Object> serviceHealthMap = new HashMap<>();
        serviceHealthMap.put("service1", service1Health);
        serviceHealthMap.put("service2", service2Health);

        if ("up".equals(service1Health) && "up".equals(service2Health)) {
            return Health.up().withDetails(serviceHealthMap).build();
        } else {
            return Health.down().withDetails(serviceHealthMap).build();
        }
    }

    public String checkService1Health() {
        return "up";
    }

    public String checkService2Health() {
        return "up";
    }
}

By default, details are not shown, you need to enable it in application.properties file by setting management.endpoint.health.show-details property. Values are never, always and when-authorized.

1
management.endpoint.health.show-details=always

Sample response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "status": "UP",
  "details": {
    "services": {
      "status": "UP",
      "details": { "service2": "up", "service1": "up" }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 234685313024,
        "free": 172010881024,
        "threshold": 10485760
      }
    }
  }
}

Info Endpoint

http://localhost:8080/actuator/info - The info endpoint provides general information about the application. You can set the information about the application using properties with info prefix.

1
2
3
info.app.name=Sample Application
info.app.description=Desc
info.app.version=1.0.0

sample response

1
2
3
4
5
6
7
{
  "app": {
    "name": "Sample Application",
    "description": "Desc",
    "version": "1.0.0"
  }
}

Beans

http://localhost:8080/actuator/beans - Shows all the beans’ aliases, scope, type, resource and dependencies.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "contexts": {
    "application": {
      "beans": {
        "endpointCachingOperationInvokerAdvisor": {
          "aliases": [],
          "scope": "singleton",
          "type": "org.springframework.boot.actuate.endpoint.invoker.cache.CachingOperationInvokerAdvisor",
          "resource": "class path resource [org/springframework/boot/actuate/autoconfigure/endpoint/EndpointAutoConfiguration.class]",
          "dependencies": ["environment"]
        },
        "defaultServletHandlerMapping": {
          "aliases": [],
          "scope": "singleton",
          "type": "org.springframework.web.servlet.HandlerMapping",
          "resource": "class path resource [org/springframework/boot/autoconfigure/web/servlet/WebMvcAutoConfiguration$EnableWebMvcConfiguration.class]",
          "dependencies": []
        }
      }
    }
  }
}

Mappings

http://localhost:8080/actuator/mappings - Shows all the mapping information

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "handler": "public java.lang.String com.example.demo.controller.HelloController.sayHello()",
  "predicate": "{ /hello}",
  "details": {
    "handlerMethod": {
      "className": "com.example.demo.controller.HelloController",
      "name": "sayHello",
      "descriptor": "()Ljava/lang/String;"
    },
    "requestMappingConditions": {
      "consumes": [],
      "headers": [],
      "methods": [],
      "params": [],
      "patterns": ["/hello"],
      "produces": []
    }
  }
}

scheduledtasks

http://localhost:8080/actuator/scheduledtasks - check scheduled tasks

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "cron": [],
  "fixedDelay": [],
  "fixedRate": [
    {
      "runnable": {
        "target": "com.example.demo.Application.someJob"
      },
      "initialDelay": 0,
      "interval": 2000
    }
  ],
  "custom": []
}

Httptrace

shows http trace. It includes detailed information about the request and response. Sample response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
  "traces": [
     {
      "timestamp": "2019-05-27T09:29:55.652Z",
      "principal": null,
      "session": null,
      "request": {
        "method": "GET",
        "uri": "http://localhost:8080/favicon.ico",
        "headers": {
          "referer": ["http://localhost:8080/hello"],
          "accept-language": [
            "en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7,zh-TW;q=0.6"
          ],
          "host": ["localhost:8080"],
          "connection": ["keep-alive"],
          "cache-control": ["no-cache"],
          "accept-encoding": ["gzip, deflate, br"],
          "pragma": ["no-cache"],
          "accept": ["image/webp,image/apng,image/*,*/*;q=0.8"],
          "user-agent": [
            "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.157 Safari/537.36"
          ]
        },
        "remoteAddress": null
      },
      "response": {
        "status": 200,
        "headers": {
          "Accept-Ranges": ["bytes"],
          "Last-Modified": ["Tue, 30 Apr 2019 06:18:32 GMT"],
          "Content-Length": ["946"],
          "Date": ["Mon, 27 May 2019 09:29:55 GMT"],
          "Content-Type": ["image/x-icon"]
        }
      },
      "timeTaken": 2
    },
    ...
  ]
}

Threaddump

http://localhost:8080/actuator/threaddump - dumps threads

Shutdown

This endpoint is very dangerous so keeping it disabled is recommended. To enable this endpoint, add the following line to application.properties file:

1
management.endpoint.shutdown.enabled=true

shutdown only support POST request

1
2
$ curl -X POST "http://localhost:8080/actuator/shutdown"
{"message":"Shutting down, bye..."}

Reference

source code: SpringBootExamples - actuator