SpringBoot如何利用Actuator來監控應用？

• 2020 年 12 月 13 日
• 筆記
• springboot

Actuator是什麼？

官網：Spring Boot Actuator: Production-ready Features

先從官網摘幾句文縐縐的解釋：

• SpringBoot可以幫助你再將應用程序推向生產環境時對其進行監視和管理。

• 你可以選擇使用http斷點或JMX來管理和監視應用程序。

• 審計【auditing】、健康【health】和指標收集【metrics gathering】可以自動應用到你的應用程序中。

總結一下就是：Actuator就是用來監控你的應用程序的。

快速開始

引入依賴

        <!--Actuator-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        <!--Spring MVC 自動化配置-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

一般來說這兩個依賴都是相互配合的。

yml與自動配置

下面是一段yml的配置：

server:
  port: 8081
management:
  endpoints:
    web:
      base-path: /actuator # Actuator 提供的 API 接口的根目錄
      exposure:
        include: '*'  # 需要開放的端點
        exclude: # 需要排除的端點

• management.endpoints.web對應的配置類是：org.springframework.boot.actuate.autoconfigure.endpoint.web.WebEndpointProperties。

• 相關的自動配置在org.springframework.boot.actuate.autoconfigure.endpoint.web.WebEndpointAutoConfiguration中完成，感興趣的同學可以查看一下源碼。

• basePath是Actuator提供的API接口的根目錄，默認配置就是/actuator。

• Exposure.include表示需要開放的端點，默認只打開health和info兩個斷點，設置*可以開放所有端點 。

• Exposure.include表示排除的端點，設置*為排除所有的端點。

主程序類

@SpringBootApplication
public class SpringBootActuatorApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringBootActuatorApplication.class, args);
    }

}

測試

訪問//localhost:8081/actuator/health，得到應用的健康信息如下：

{
  status: "UP"  // 開啟
}

Endpoints

由於我們設置開放了所有的Endpoints，啟動程序時，我們能夠看到控制台輸出：

[  restartedMain] o.s.b.a.e.web.EndpointLinksResolver      : Exposing 13 endpoint(s) beneath base path '/actuator'

說的很清楚，總共暴露了內置的13個端點，這些端點，SpringBoot文檔已經交代地非常詳細啦。

其實內置的端點不止13個，官方文檔說：每個端點可以被enabled or disabled和exposed over HTTP or JMX。只有當端點同時enabled和exposed的時候才可用，內置的端點也只有在自動配置生效的時候才可用。

大多數的應用程序會選擇HTTP暴露端點，我們可以通過/actuator/health訪問ID為health的端點。

官方列舉的所有端點列表

JMX和web共有的

如果你的是web應用 (Spring MVC, Spring WebFlux, or Jersey)，你可以使用下面這些額外的端點:

啟動端點

如果你希望啟動某個端點，你可以按照management.endpoint.<id>.enabled的配置啟動，以shutdown端點為例：

management:
  endpoint:
    shutdown:
      enabled: true

如果你只希望啟動某個端點，你可以向下面這樣：

management:
  endpoints:
    enabled-by-default: false # 不啟用默認配置
  endpoint:
    info:
      enabled: true

這個示例，只會啟用info端點。

暴露端點

端點可能會包含銘感信息，考慮暴露的時候應當慎重考慮。

• web程序默認暴露的端點有且僅有兩個：health和info。

• JMX程序默認暴露所有的端點。

我們可以使用include和exclude屬性來控制端點是否需要暴露。下面是兩個例子

一、不讓JMX暴露所有端點，只讓它暴露health和info兩個端點。

management:
  endpoints:
    jmx:
      exposure:
        include: "health,info"

二、暴露web除env和beans之外的所有端點。

management:
  endpoints:
    web:
      exposure:
        include: "*"
        exclude: "env,beans"

management.endpoints.web.exposure.include=*  
management.endpoints.web.exposure.exclude=env,beans

配置端點

端點將會自動緩存對不帶任何參數的讀取操作的響應。你可以使用cache.time-to-live屬性配置。

以下示例將Bean端點的緩存的生存時間設置為10秒。

management:
  endpoint:
    beans:
      cache:
        time-to-live: "10s"

發現頁面

默認你可以訪問/actuator頁面獲得所有的端點信息：

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

跨域支持

默認情況下，CORS支持是禁用的，並且僅在設置了management.endpoints.web.cors.allowed-origins屬性後才啟用。 以下配置允許來自example.com域的GET和POST調用：

management:
  endpoints:
    web:
      cors:
        allowed-origins: "//example.com"
        allowed-methods: "GET,POST"

完整的選項可以查看：CorsEndpointProperties

實現一個定義的端點

我們直接來看一個例子吧：

@Component  // 讓Spring容器管理
@Endpoint(id = "myEndPoint") //web和jmx公用， @WebEndpoint表示指定web
public class MyEndpoint {

    Runtime runtime = Runtime.getRuntime();

    @ReadOperation // 讀操作
    public Map<String, Object> getData() {
        Map<String, Object> map = new HashMap<>();
        map.put("available-processors", runtime.availableProcessors());
        map.put("free-memory", runtime.freeMemory());
        map.put("max-memory", runtime.maxMemory());
        map.put("total-memory", runtime.totalMemory());
        return map;
    }
}

• @Component表明讓這個bean給Spring容器管理。
• @Endpoint標註這是個端點，類似的還有@WebEndpoint標註的是特指web程序。
• id = "myEndPoint"限制訪問端點的路徑：/actuator/myEndPoint。
• @ReadOperation規定HTTP請求的方法為GET，@ReadOperation為POST，@DeleteOperation為DELETE。

接下來我們測試一下，再測試之前，不要忘了yml中啟動設置：

server:
  port: 8081

management:
  endpoints:
    web:
      exposure:
        include: '*' # 需要開放的端點。默認值只打開 health 和 info 兩個端點。通過設置 * 
    enabled-by-default: false
  endpoint:
    myEndPoint:
      enabled: true

我們暫時關閉其他所有的端點，只關注myEndPoint端點，接着啟動程序，訪問：//localhost:8081/actuator/myEndPoint，獲得json信息。

{
    max-memory: 3787980800,
    free-memory: 235775968,
    available-processors: 4,
    total-memory: 298844160
}

實際上如果是用於SpringMVC或Spring WebFlux，我們可以使用@RestControllerEndpoint或@ControllerEndpoint註解，定義一個更符合我們平時web開發模式的端點，你可以看一下下面這個例子。

@Component
@RestControllerEndpoint(id = "web")
public class MyWebEndPoint {
    @GetMapping("/")
    public Map<String, Object> getData() {
		// ...
        return map;
    }
}

Health端點

端點這麼多，我們挑幾個學習一下，health作為默認開放的端點之一，還是需要好好了解一下的。

設置何時顯示信息

你可以使用得到的健康信息去檢查你的應用程序，暴露的health信息依賴於下面兩個屬性配置：

management.endpoint.health.show-details
management.endpoint.health.show-components

這兩個屬性可以設置的值如下：

health端點通過健康指示器HealthIndicator獲取不同的資源的健康信息，且Autuator內置了多個HealthIndicator的實現，太多啦太多啦，如果需要可以看看官網 Auto-configured HealthIndicators。

另外，如果你想啟用或者禁用指定的指示器，你可以配置management.health.key.enabled，key需要被替換，官網表格上有。

如果你想設置全部的，你可以配置management.health.defaults.enabled

設置順序

你可以通過以下設置顯示順序：

management:
  endpoint:
    health:
      status:
        order: "fatal,down,out-of-service,unknown,up"

設置響應碼

響應碼反應了總體健康狀態。默認情況下，OUT_OF_SERVICE和DOWN的映射為503，其他狀態為200。你可以按照下面的方式設置映射：

management:
  endpoint:
    health:
      status:
        http-mapping:
          down: 503
          fatal: 503
          out-of-service: 503

自定義健康信息

縱使，Actuator已經提供了許多內置實現，總會滿足不了我們的需求，那如何去自定義呢？

• 註冊實現HealthIndicator接口的Spring Bean。
• 提供health()方法的實現並返回健康響應，包括狀態和其他需要顯示的詳細信息。

以下代碼展示了一個案例：

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
import java.util.Random;

@Component
public class MyHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        // perform some specific health check
        boolean check = check();
        if (!check) {
            return Health.down().withDetail("Error Code", 0).build();
        }
        return Health.up().build();
    }

    private boolean check() {
        return new Random().nextBoolean();
    }

}

id就是bena的名稱去掉HealthIndicator後綴，這裡id就是my。

看看相關的yml怎麼配置？

management:
  endpoints:
    web:
      exposure:
        include: '*' # 需要開放的端點。默認值只打開 health 和 info 兩個端點。通過設置 * ，可以開放所有端點。
    enabled-by-default: false
  endpoint:
    health:
      enabled: true
      show-details: always # 何時顯示完整的健康信息
      show-components: always
      status:
        http-mapping: # 設置不同健康狀態對應的響應狀態碼
          DOWN: 503
        order: FATAL, DOWN, OUT_OF_SERVICE, UP, UNKNOWN # 狀態排序

測試一下，訪問：/actuator/health，可以嘗試多點幾次，會出現UP和DOWN的情況，得到以下信息：

{
  status: "DOWN",
  components: {
    diskSpace: {
      status: "UP",
      details: {
        total: 267117391872,
        free: 130840469504,
        threshold: 10485760,
        exists: true
      }
    },
    my: {
      status: "DOWN",
      details: {
        Error Code: 0
      }
    },
    ping: {
      status: "UP"
    }
  }
}

• my對應的就是我們自定義的MyHealthIndicator，裏面詳細的信息有：狀態status，信息details。
• diskSpace對應DiskSpaceHealthIndicator，ping對應的是PingHealthIndicator。

其他的端點，感興趣的小夥伴可以去到官網一一測試，總之，通過這些Actuator提供的端點，我們很容易就能夠監控管理我們的應用程序。

源碼下載

本文內容均為對優秀博客及官方文檔總結而得，原文地址均已在文中參考閱讀處標註。最後，文中的代碼樣例已經全部上傳至Gitee：//gitee.com/tqbx/springboot-samples-learn。

參考閱讀

• Spring Boot Actuator: Production-ready Features
• SpringBoot重點詳解–使用Actuator進行健康監控