聊聊springboot項目如何實現自定義actuator端點

前言

用過springboot的朋友，可能會知道springboot有四大神器：自動裝配、starter、cli、actuator。其中actuator可幫助你在將應用程序推送到生產環境時監控和管理應用程序。你可以選擇使用 HTTP 端點或 JMX 來管理和監控你的應用程序。 審計、健康和指標收集也可以自動應用於你的應用程序。

actuator默認為我們內置了以下端點

ID	描述	默認啟用	默認公開
auditevents	公開當前應用程序的審計事件信息	Yes	No
beans	顯示應用程序中所有Spring bean的完整列表	Yes	No
conditions	顯示在配置和自動配置類上評估的條件以及它們是否匹配的原因	Yes	No
configprops	顯示所有@ConfigurationProperties對照的列表	Yes	No
env	從Spring的ConfigurableEnvironment中公開屬性	Yes	No
flyway	顯示已應用的任何Flyway數據庫遷移	Yes	No
health	顯示應用程序健康信息	Yes	Yes
httptrace	顯示HTTP跟蹤信息（默認情況下，最后100個HTTP請求-響應交互）	Yes	No
info	顯示任意應用程序信息	Yes	Yes
loggers	顯示和修改應用程序中記錄器的配置	Yes	No
liquibase	顯示已應用的任何Liquibase數據庫遷移	Yes	No
metrics	顯示當前應用程序的“指標”信息	Yes	No
mappings	顯示所有@RequestMapping路徑對照的列表	Yes	No
scheduledtasks	顯示應用程序中調度的任務	Yes	No
sessions	允許從Spring Session支持的會話存儲中檢索和刪除用戶會話	Yes	No
shutdown	讓應用程序優雅地關閉	No	No
threaddump	執行線程轉儲	Yes	No

如果你的應用程序是一個web應用程序（Spring MVC、Spring WebFlux或Jersey），你可以使用以下附加端點

ID	描述	默認啟用	默認公開
heapdump	返回一個GZip壓縮的hprof堆轉儲文件	Yes	No
jolokia	在HTTP上公開JMX bean（當Jolokia在類路徑上時，WebFlux不可用）	Yes	No
logfile	返回日志文件的內容，支持使用HTTP Range header來檢索日志文件內容的一部分	Yes	No
prometheus	公開指標，該格式可以被Prometheus服務器采集	Yes	No

注： actuator 在springboot 1.X 和springboot 2.X 存在較大的差異，本文以springboot 2.X 作為本文的講解

通常情況下，actuator內置的端點就可以滿足我們的日常需求了，但有時候我們需要自定義端點。下面就列舉一下幾種常用的自定義端點

自定義端點

自定義前置條件，在pom.xml引入

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

1、自定義health

當內置的health端點信息不滿足用來判斷我們項目是否健康時，我們可以自定義health

通過實現org.springframework.boot.actuate.health.HealthIndicator接口，形如

@Component
public class CustomHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        int errorCode = check();
        if (errorCode == 1) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }

    private int check() {
        // perform some specific health check
        return ThreadLocalRandom.current().nextInt(5);
    }

}

或者通過繼承org.springframework.boot.actuate.health.AbstractHealthIndicator，形如

@Component("otherCustom")
public class CustomAbstractHealthIndicator extends AbstractHealthIndicator {
    @Override
    protected void doHealthCheck(Health.Builder builder) throws Exception {

        int errorCode = check();
        if (errorCode == 1) {
            builder.down().down().withDetail("Error Code", errorCode).build();
            return;
        }
        builder.up().build();

    }

    private int check() {
        // perform some specific health check
        return ThreadLocalRandom.current().nextInt(5);
    }
}

推薦使用繼承AbstractHealthIndicator 這種方式。在配置文件中作如下配置，可以查看詳細的健康信息

management:
   endpoint:
      health:
        show-details: always

通過訪問http://ip:port/actuator/health進行查看，形如下

從圖片我們可以看出，我們自定義的health端點信息，如果@Component不指定name，形如CustomHealthIndicator ，默認是取custom作為自定義端點對象

2、自定義info

我們可以通過實現org.springframework.boot.actuate.info.InfoContributor接口，來暴露一些我們想展示的信息。形如

@Component
public class CustomInfoContributor implements InfoContributor {

    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("customInfo", Collections.singletonMap("hello", "world"));
    }

}

通過訪問http://ip:port/actuator/info進行查看，形如下

3、自定義endpoint

有時候我們需要自定義自己的端點，我們可以通過
@Endpoint注解 + @ReadOperation、@WriteOperation、@DeleteOperation注解來實現自定義端點。形如下

@Component
@Endpoint(id = "customEndpoint")
public class CustomEndpoint {

  // @ReadOperation 對應GET請求

  /**
   * 請求示例：
   * GET http://localhost:8080/actuator/customEndpoint/zhangsan/20
   * @param username
   * @param age
   *
   * @return
   */
  @ReadOperation
  public Map<String, Object> endpointByGet(@Selector String username,@Selector Integer age) {
    Map<String, Object> customMap = new HashMap<>();
    customMap.put("httpMethod", HttpMethod.GET.toString());
    customMap.put("username",username);
    customMap.put("age",age);
    return customMap;
  }


  // @WriteOperation 對應POST請求

  /**
   * 請求示例：
   * POST http://localhost:8080/actuator/customEndpoint
   *
   * 請求參數為json格式
   *
   * {
   *     "username": "zhangsan",
   *     "age": 20
   * }
   *
   * @param username 參數都為必填項
   * @param age 參數都為必填項
   * @return
   */
  @WriteOperation
  public Map<String, Object> endpointByPost(String username,Integer age) {
    Map<String, Object> customMap = new HashMap<>();
    customMap.put("httpMethod", HttpMethod.POST.toString());
    customMap.put("username",username);
    customMap.put("age",age);
    return customMap;
  }


  // @DeleteOperation 對應Delete請求

  /**
   * 請求示例：
   * DELETE http://localhost:8080/actuator/customEndpoint
   *
   * @return
   */
  @DeleteOperation
  public Map<String, Object> endpointByDelete() {
    Map<String, Object> customMap = new HashMap<>();
    customMap.put("httpMethod", HttpMethod.DELETE.toString());

    return customMap;
  }

代碼片段里面有比較詳細的注釋，這邊就不在論述。這邊有個細節就是，我們需要在yml作如下配置來暴露我們自定義的端點

通過

management:
  endpoints:
    web:
      exposure:
        include: customEndpoint

或者

management:
  endpoints:
    web:
      exposure:
        include: "*"

總結

本文僅介紹幾種相對通用的自定義端點，更詳細的端點介紹可以查看官網，鏈接如下

https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator

demo鏈接

https://github.com/lyb-geek/springboot-learning/tree/master/springboot-custom-actuator-endpoint