Spring Boot Actuator快速入門

不知道大家在寫 Spring Boot 項(xiàng)目的過程中，使用過 Spring Boot Actuator 嗎？知道 Spring Boot Actuator 是什么，干什么的嗎？今天就要來給大家介紹一下 Spring Boot Actuator，學(xué)習(xí)如何在 Spring Boot 2.x 中使用、配置和擴(kuò)展這個(gè)監(jiān)控工具。Spring Boot 1.x 的使用就不再這邊介紹了。相信大家平時(shí)使用的框架基本上都要升級到 2.x了吧。

什么是 Actuator ？

從本質(zhì)上講，Spring Boot Actuator 為我們的應(yīng)用程序帶來了生產(chǎn)就緒的功能。監(jiān)控我們的應(yīng)用程序，收集指標(biāo)，了解流量，或者是數(shù)據(jù)庫的狀態(tài)。有了它，我們就可以很簡單的監(jiān)控應(yīng)用程序的各種指標(biāo)數(shù)據(jù)。

Spring Boot Actuator 使用 http 或者 JMX 的方式來公開運(yùn)行中的應(yīng)用程序的操作信息--健康、指標(biāo)、信息、轉(zhuǎn)儲、環(huán)境等，我們能夠方便的與它互動。只要添加Spring Boot Actuator 依賴到 classpath 中，就有幾個(gè)指標(biāo)路徑可供我們開箱使用。與大多數(shù) Spring boot 模塊一樣，我們可以很容易地以多種方式配置或擴(kuò)展它。

快速入門

要想啟用 Spring Boot Actuator，我們只需在軟件包管理器中添加 spring-boot-starter-actuator 依賴項(xiàng)。在 pom.xml 文件添加如下代碼即可：

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

是吧，很簡單就添加好了。有的小朋友可能會有疑問了，為什么沒有添加 version 節(jié)點(diǎn)呢？那是因?yàn)?Spring Boot 的 parent pom 會制定版本號，所以這里無需再次指定了。

Spring Boot 2.x Actuator

在 2.x 版本中，Spring Boot Actuator 保持了 1.x 的基本操作，但簡化了它的模型，擴(kuò)展了它的能力，并加入了更好的默認(rèn)值。這個(gè)版本變得與技術(shù)無關(guān)。它還簡化了其安全模型，將其與應(yīng)用程序模型合并。最新版本現(xiàn)在支持CRUD模型，而不是舊的讀寫模型。

技術(shù)支持

在 2.x 中，Spring Boot Actuator 將其模型定義為可插拔和可擴(kuò)展的，而不依賴于 MVC。通過這個(gè)新的模型，我們能夠利用 MVC 以及 WebFlux 作為底層 Web 技術(shù)的優(yōu)勢。此外，可以通過實(shí)現(xiàn)正確的適配器來添加即將到來的技術(shù)。不過 JMX 仍然被支持，無需任何額外的代碼就可以暴露路徑。

重要變化

與以前的版本不同，Spring Boot Actuator 的大多數(shù)路徑都是禁用的。默認(rèn)情況下，只有 /health 和 /info 兩個(gè)可用。如果我們想啟用所有的路徑，可以設(shè)置 management.endpoints.web.exposure.include=* 來實(shí)現(xiàn)。Actuator 現(xiàn)在與常規(guī)的 App 安全規(guī)則共享安全配置，所以安全模型被大大簡化。要調(diào)整 Actuator 的安全規(guī)則，我們可以只添加一個(gè) /actuator/** 的條目。

@Bean
public SecurityWebFilterChain securityWebFilterChain(
  ServerHttpSecurity http) {
    return http.authorizeExchange()
      .pathMatchers("/actuator/**").permitAll()
      .anyExchange().authenticated()
      .and().build();
}

我們可以在全新的 Actuator 官方文檔中找到進(jìn)一步的細(xì)節(jié)。另外，在默認(rèn)情況下，所有的 Actuator 路徑現(xiàn)在都被放在 /actuator 路徑下。和以前的版本一樣，我們可以使用新的屬性management.endpoints.web.base-path 來調(diào)整這個(gè)路徑。

預(yù)定義的路徑

讓我們看看一些可用的路徑，其中大部分在1.x中已經(jīng)可用。另外，有些路徑被添加了，有些被刪除了，有些被重組了。

• /auditevents 列出了安全審計(jì)相關(guān)的事件，如用戶登錄/注銷。此外，我們還可以通過本金或類型以及其他字段進(jìn)行過濾。
• /beans 返回我們BeanFactory中所有可用的bean。與/auditevents不同，它不支持過濾。
• /conditions，以前被稱為/autoconfig，圍繞自動配置建立一個(gè)條件報(bào)告。
• /configprops 允許我們獲取所有@ConfigurationProperties。
• /env 返回當(dāng)前的環(huán)境屬性。此外，我們還可以檢索單個(gè)屬性。
• /flyway 提供了關(guān)于我們Flyway數(shù)據(jù)庫遷移的細(xì)節(jié)。
• /health 總結(jié)了我們應(yīng)用程序的健康狀態(tài)。
• /heapdump 構(gòu)建并返回我們應(yīng)用程序使用的 JVM 的堆存儲。
• /info 返回一般信息。它可能是自定義數(shù)據(jù)、構(gòu)建信息或關(guān)于最新提交的細(xì)節(jié)。
• /liquibase 的行為類似于/flyway，但針對Liquibase。
• /logfile 返回普通的應(yīng)用程序日志。
• /loggers 使我們能夠查詢和修改我們應(yīng)用程序的日志級別。
• /metrics 詳細(xì)說明我們應(yīng)用程序的指標(biāo)。這可能包括通用指標(biāo)和自定義指標(biāo)。
• /prometheus 返回與前面一樣的指標(biāo)，但格式化為與Prometheus服務(wù)器一起工作。
• /scheduledtasks 提供了關(guān)于我們應(yīng)用程序中每個(gè)計(jì)劃任務(wù)的細(xì)節(jié)。
• /sessions 列出HTTP會話，因?yàn)槲覀兪褂玫氖荢pring Session。
• /shutdown 執(zhí)行應(yīng)用程序的優(yōu)雅關(guān)閉。
• /threaddump 轉(zhuǎn)儲底層JVM的線程信息。

執(zhí)行器路徑的超媒體

Spring Boot 增加了一個(gè)所有路徑的集合入口，可以返回所有可用的執(zhí)行器路徑的鏈接。這將有助于發(fā)現(xiàn)執(zhí)行器路徑及其相應(yīng)的URL。默認(rèn)情況下，這個(gè)集合入口可以通過 /actuator 路徑訪問。因此，如果我們向這個(gè)URL發(fā)送一個(gè)GET請求，它將返回各種路徑的執(zhí)行器鏈接。

{
  "_links": {
    "self": {
      "href": "http://localhost:8080/actuator",
      "templated": false
    },
    "features-arg0": {
      "href": "http://localhost:8080/actuator/features/{arg0}",
      "templated": true
    },
    "features": {
      "href": "http://localhost:8080/actuator/features",
      "templated": false
    },
    "beans": {
      "href": "http://localhost:8080/actuator/beans",
      "templated": false
    },
    "caches-cache": {
      "href": "http://localhost:8080/actuator/caches/{cache}",
      "templated": true
    },
    // ...
}

如上所示，/actuator 路徑在 _links 字段下報(bào)告所有可用的執(zhí)行器路徑。如果我們配置了一個(gè)自定義的管理基礎(chǔ)路徑，那么我們應(yīng)該能使用該集合入口發(fā)現(xiàn)URL。例如，如果我們將management.endpoints.web.base-path 設(shè)置為 /mgmt ，那么我們應(yīng)該向 /mgmt 路徑發(fā)送請求，以查看鏈接列表。但是如果當(dāng)管理集合入口被設(shè)置為 / 時(shí)，集合入口被禁用，以防止與其他映射發(fā)生沖突的可能性。

健康指示器

就像以前的版本一樣，我們可以很容易地添加自定義指標(biāo)。與其他 API 相反，用于創(chuàng)建自定義健康路徑的抽象概念保持不變。然而，一個(gè)新的接口，即 ReactiveHealthIndicator，已經(jīng)被添加到實(shí)現(xiàn)反應(yīng)式健康檢查。讓我們來看看一個(gè)簡單的自定義反應(yīng)式健康檢查。

@Component
public class DownstreamServiceHealthIndicator implements ReactiveHealthIndicator {
    @Override
    public Mono< Health > health() {
        return checkDownstreamServiceHealth().onErrorResume(
          ex - > Mono.just(new Health.Builder().down(ex).build())
        );
    }
    private Mono< Health > checkDownstreamServiceHealth() {
        return Mono.just(new Health.Builder().up().build());
    }
}

健康指標(biāo)的一個(gè)方便的特點(diǎn)是，我們可以把它們作為一個(gè)層次結(jié)構(gòu)的一部分進(jìn)行匯總。因此，按照前面的例子，我們可以把所有的下游服務(wù)歸入一個(gè)下游服務(wù)類別。只要每個(gè)嵌套的服務(wù)都是可以到達(dá)的，這個(gè)類別就會是健康的。

健康組

從 Spring Boot 2.2 開始，我們可以將健康指標(biāo)組織成組，并對所有組員應(yīng)用相同的配置。例如，我們可以通過在 application.properties 中添加以下內(nèi)容來創(chuàng)建一個(gè)名為 custom 的健康組。

management.endpoint.health.group.custom.include=diskSpace,ping

這樣，自定義組包含 diskSpace 和 ping 健康指標(biāo)?，F(xiàn)在，如果我們調(diào)用 /actuator/health 路徑，它將在 JSON 響應(yīng)中告訴我們關(guān)于新的健康組。

{"status":"UP","groups":["custom"]}

通過健康組，我們可以看到一些健康指標(biāo)的匯總結(jié)果。在這種情況下，如果我們向 /actuator/health/custom 發(fā)送一個(gè)請求，

{"status": "UP"}

我們可以通過 application.properties 來配置該組，以顯示更多細(xì)節(jié)。

management.endpoint.health.group.custom.show-components=always
management.endpoint.health.group.custom.show-details=always

現(xiàn)在，如果我們向 /actuator/health/custom 發(fā)送同樣的請求，我們會看到更多的細(xì)節(jié)。

{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 499963170816,
        "free": 91300069376,
        "threshold": 10485760
      }
    },
    "ping": {
      "status": "UP"
    }
  }
}

也可以只為授權(quán)用戶顯示這些細(xì)節(jié)。

management.endpoint.health.group.custom.show-components=when_authorized
management.endpoint.health.group.custom.show-details=when_authorized

我們還可以有一個(gè)自定義的狀態(tài)映射。例如，它可以不返回 HTTP 200 OK 響應(yīng)，而是返回 207 狀態(tài)代碼。

management.endpoint.health.group.custom.status.http-mapping.up=207

在這里，我們要告訴 Spring Boot，如果自定義組的狀態(tài)是 UP，就返回 207 的 HTTP 狀態(tài)代碼。

Spring Boot 2中的度量

在 Spring Boot 2.0 中，內(nèi)部指標(biāo)被 Micrometer 支持所取代，因此我們可以預(yù)期會有一些變化。如果我們的應(yīng)用程序正在使用 GaugeService 或 CounterService 等度量衡服務(wù)，它們將不再可用。

相反，我們要與 Micrometer 直接互動。在 Spring Boot 2.0 中，我們會得到一個(gè)自動配置的 MeterRegistry 類型的 bean。此外，Micrometer 現(xiàn)在是 Actuator 依賴的一部分，所以只要 Actuator 的依賴在 classpath 中，我們就應(yīng)該可以使用了。此外，我們將從 /metrics 端點(diǎn)得到一個(gè)全新的響應(yīng)。

{
  "names": [
    "jvm.gc.pause",
    "jvm.buffer.memory.used",
    "jvm.memory.used",
    "jvm.buffer.count",
    // ...
  ]
}

正如我們所看到的，沒有像我們在1.x中得到的實(shí)際度量。為了得到一個(gè)特定指標(biāo)的實(shí)際值，我們現(xiàn)在可以導(dǎo)航到所需的指標(biāo)，例如，/actuator/metrics/jvm.gc.pause，然后得到一個(gè)詳細(xì)的響應(yīng)。

{
  "name": "jvm.gc.pause",
  "measurements": [
    {
      "statistic": "Count",
      "value": 3.0
    },
    {
      "statistic": "TotalTime",
      "value": 7.9E7
    },
    {
      "statistic": "Max",
      "value": 7.9E7
    }
  ],
  "availableTags": [
    {
      "tag": "cause",
      "values": [
        "Metadata GC Threshold",
        "Allocation Failure"
      ]
    },
    {
      "tag": "action",
      "values": [
        "end of minor GC",
        "end of major GC"
      ]
    }
  ]
}

現(xiàn)在的度量標(biāo)準(zhǔn)要徹底得多，不僅包括不同的值，還包括一些相關(guān)的元數(shù)據(jù)。

創(chuàng)建一個(gè)自定義路徑

正如我們之前指出的，我們可以創(chuàng)建自定義路徑。不過，Spring Boot 2重新設(shè)計(jì)了實(shí)現(xiàn)的方式，以支持新的技術(shù)無關(guān)的范式。讓我們創(chuàng)建一個(gè)Actuator路徑，在我們的應(yīng)用程序中查詢、啟用和禁用功能標(biāo)志。

@Component
@Endpoint(id = "features")
public class FeaturesEndpoint {
    private Map< String, Feature > features = new ConcurrentHashMap<  >();
    @ReadOperation
    public Map< String, Feature > features() {
        return features;
    }
    @ReadOperation
    public Feature feature(@Selector String name) {
        return features.get(name);
    }
    @WriteOperation
    public void configureFeature(@Selector String name, Feature feature) {
        features.put(name, feature);
    }
    @DeleteOperation
    public void deleteFeature(@Selector String name) {
        features.remove(name);
    }
    public static class Feature {
        private Boolean enabled;
        // [...] getters and setters 
    }
}

為了獲得路徑，我們需要一個(gè)Bean。在我們的例子中，我們使用@Component來做這個(gè)。同時(shí)，我們需要用@Endpoint來裝飾這個(gè)Bean。我們的端點(diǎn)的路徑是由@Endpoint的id參數(shù)決定的。在我們的例子中，它將把請求路由到/actuator/features。一旦準(zhǔn)備就緒，我們就可以開始使用定義操作了。

• @ReadOperation。它將映射到HTTP GET。
• @WriteOperation。它將映射到HTTP POST。
• @DeleteOperation。它將映射到HTTP DELETE。

當(dāng)我們在應(yīng)用程序中使用前一個(gè)端點(diǎn)運(yùn)行應(yīng)用程序時(shí)，Spring Boot將注冊它。驗(yàn)證這一點(diǎn)的一個(gè)快速方法是檢查日志。

擴(kuò)展現(xiàn)有的端點(diǎn)

想象一下，如果我們想確保應(yīng)用程序的生產(chǎn)實(shí)例永遠(yuǎn)不是SNAPSHOT版本。我們決定通過改變返回該信息的 Actuator 端點(diǎn)的HTTP狀態(tài)代碼，即/info來做到這一點(diǎn)。如果我們的應(yīng)用程序碰巧是SNAPSHOT，我們會得到一個(gè)不同的HTTP狀態(tài)代碼。

我們可以使用 @EndpointExtension 注解，或其更具體的特殊化@EndpointWebExtension或@EndpointJmxExtension，輕松地?cái)U(kuò)展預(yù)定義端點(diǎn)的行為。

@Component
@EndpointWebExtension(endpoint = InfoEndpoint.class)
public class InfoWebEndpointExtension {
    private InfoEndpoint delegate;
    @ReadOperation
    public WebEndpointResponse< Map > info() {
        Map< String, Object > info = this.delegate.info();
        Integer status = getStatus(info);
        return new WebEndpointResponse<  >(info, status);
    }
    private Integer getStatus(Map< String, Object > info) {
        return 200;
    }
}

啟用所有端點(diǎn)

為了能夠使用 HTTP 訪問 Actuator 的端點(diǎn)，我們需要啟用和公開它們。默認(rèn)情況下，除了/shutdown，所有的端點(diǎn)都是啟用的。默認(rèn)情況下，只有/health和/info這兩個(gè)端點(diǎn)是公開的。我們需要添加以下配置來公開所有端點(diǎn)。

management.endpoints.web.exposure.include=*

要明確地啟用一個(gè)特定的端點(diǎn)（例如，/shutdown）

management.endpoint.shutdown.enabled=true

要公開所有已啟用的端點(diǎn)，除了一個(gè)（例如，/loggers）

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=loggers

總結(jié)

在這篇文章中，我們談到了Spring Boot Actuator。我們首先解釋了Actuator的含義以及它為我們做了什么。接下來，我們重點(diǎn)討論了當(dāng)前Spring Boot 2.x版本的Actuator，討論了如何使用它、調(diào)整它和擴(kuò)展它。我們還談到了在這個(gè)新的迭代中我們可以發(fā)現(xiàn)的重要的安全變化。我們討論了一些流行的端點(diǎn)，以及它們是如何變化的。