知識庫 / Spring / Spring Boot RSS 訂閱

{
  "_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
    },
    // truncated
}

如上所示，/actuator 端點報告了所有在 _links 字段下可用的 actuator 端點。

此外，如果配置了自定義管理基礎路徑，則應使用該基礎路徑作為發現 URL。

例如，如果將 management.endpoints.web.base-path 設置為 /mgmt，則應請求 /mgmt 端點以查看鏈接列表。

有趣的是，當管理基礎路徑設置為 / 時，為了防止與其他映射衝突，禁用發現端點。

3.5. 健康指標

與前版本類似，我們可以輕鬆地添加自定義指標。與其它API不同，創建自定義健康端點的抽象層保持不變。但是，ReactiveHealthIndicator 這種新的接口已添加，用於實現反應式健康檢查。

讓我們來看一個簡單的反應式健康檢查示例：

@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() {
        // we could use WebClient to check health reactively
        return Mono.just(new Health.Builder().up().build());
    }
}

健康指標的一個實用功能是我們可以將其聚合為層次結構的一部分。

因此，遵循之前的示例，我們可以將所有下游服務分組到一個 downstream-services 類別下。只要每個嵌套的 service 可訪問，這個類別就會保持健康。

請查看我們關於健康指標的文章，以獲得更深入的瞭解。

3.6. 健康組

Spring Boot 現在允許將健康指示器組織成 組，從而在所有組中的成員之間應用一致的配置。

例如，我們可以創建一個名為 custom 的健康組，通過在我們的 application.properties 中添加以下內容：

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

這樣一來，自定義組包含磁盤空間和 ping 健康指示器。

現在，如果調用 /actuator/health 端點，它將向我們提供關於健康組的新 JSON 響應：

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

與健康組合作，我們可以查看幾個健康指標的彙總結果。

在這種情況下，如果向 /actuator/health/custom 發送請求：

{"status":"UP"}

然後，我們可以通過配置組以顯示更多詳細信息，使用 application.properties：

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

現在，如果我們將相同的請求發送到 /actuator/health/custom，我們將看到更多詳細信息：

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

當然，以下是翻譯後的內容：

還可以僅向授權用户顯示這些詳細信息：

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

我們還可以配置自定義狀態映射。

例如，除了返回 HTTP 200 OK 響應外，還可以返回 207 狀態碼：

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

我們正在告訴 Spring Boot，如果 自定義組的狀態是 啓用，則返回一個 207 HTTP 狀態碼。

3.7. Spring Boot 中的指標

在 Spring Boot 中，內部指標已被 Micrometer 支持所取代，因此我們應該預期存在破壞性變更。如果我們的應用程序使用了諸如 GaugeService 或 CounterService 這樣的指標服務，它們將不再可用。

此外，Spring Boot 提供了配置自動化的 MeterRegistry Bean，允許我們直接與 Micrometer 交互以獲取指標。

更重要的是，Micrometer 現在是 Actuator 的依賴項的一部分，只要 Actuator 依賴項在類路徑中，我們就可以放心使用。

此外，/metrics 端點的響應已被完全重新設計。

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

我們能看到，指標列表不再包含直接值。要訪問特定的指標值，現在可以導航到所需的指標，例如 /actuator/metrics/jvm.gc.pause，以獲取詳細響應：

{
  "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"
      ]
    }
  ]
}

現在，指標更加全面，包括不同的值以及一些相關的元數據。

3.8. 自定義 /info 端點

/info 端點保持不變。 如前所述，我們可以使用相應的 Maven 或 Gradle 依賴項添加 Git 詳細信息：

<dependency>
    <groupId>pl.project13.maven</groupId>
    <artifactId>git-commit-id-plugin</artifactId>
</dependency>

同樣，我們還可以通過使用 Maven 或 Gradle 插件，包含構建信息，包括名稱、組和版本：

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>build-info</goal>
            </goals>
        </execution>
    </executions>
</plugin>

3.9. 創建自定義端點

正如我們之前所指出，我們可以創建自定義端點。但是，Spring Boot 已重新設計了實現這一點的流程，以支持新的、技術中立的範式。

讓我們創建一個 Actuator 端點，用於查詢、啓用和禁用應用程序中的功能標誌：

@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 
    }

}

為了獲取端點，我們需要一個 Bean。 在我們的示例中，我們使用 @Component 來實現。 此外，我們需要使用 @Endpoint 對該 Bean 進行裝飾。

為了獲取端點，我們需要一個 Bean。 在我們的示例中，我們使用 <em >@Component</em> 來實現。 此外，我們需要使用 <em >@Endpoint</em> 對該 Bean 進行裝飾。

端點的路徑由 <em >id</em> 參數的 <em >@Endpoint</em> 決定。 在我們的例子中，它會將請求路由到 <em >/actuator/features</em>。

端點的路徑由 <em >id</em> 參數的 <em >@Endpoint</em> 決定。 在我們的例子中，它會將請求路由到 <em >/actuator/features</em>。

一旦準備就緒，我們就可以使用以下方法定義操作：

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

當我們以包含先前端點的應用程序運行該應用程序時，Spring Boot 將註冊它。

驗證此操作的一種快速方法是檢查日誌：

[...].WebFluxEndpointHandlerMapping: Mapped "{[/actuator/features/{name}],
  methods=[GET],
  produces=[application/vnd.spring-boot.actuator.v2+json || application/json]}"
[...].WebFluxEndpointHandlerMapping : Mapped "{[/actuator/features],
  methods=[GET],
  produces=[application/vnd.spring-boot.actuator.v2+json || application/json]}"
[...].WebFluxEndpointHandlerMapping : Mapped "{[/actuator/features/{name}],
  methods=[POST],
  consumes=[application/vnd.spring-boot.actuator.v2+json || application/json]}"
[...].WebFluxEndpointHandlerMapping : Mapped "{[/actuator/features/{name}],
  methods=[DELETE]}"[...]

在之前的日誌中，我們可以看到 WebFlux 如何暴露我們的新端點。如果改為使用 MVC，它會簡單地委託該技術，而無需修改任何代碼。

此外，我們還需要注意以下幾點：

• 與 MVC 相比，沒有依賴項。
• 方法中存在的元數據（如 敏感、啓用…）不再存在。但是，我們可以使用 @Endpoint(id = “features”, enableByDefault = false) 啓用或禁用端點。
• 不再需要擴展特定的接口。
• 與舊的讀寫模型不同，現在可以使用 DELETE 操作，並使用 @DeleteOperation。

3.10. 擴展現有端點

假設我們希望確保應用程序的生產實例永遠不會是快照版本。

我們決定通過更改 Actuator 中 /info 端點返回信息的 HTTP 狀態碼來實現這一點。如果我們的應用程序恰好是快照版本，我們將會收到不同的 HTTP 狀態碼。

我們可以輕鬆地使用 @EndpointExtension 註解或其更具體的變體 @EndpointWebExtension 或 @EndpointJmxExtension 來擴展預定義的端點行為。

@Component
@EndpointWebExtension(endpoint = InfoEndpoint.class)
public class InfoWebEndpointExtension {

    private InfoEndpoint delegate;

    // standard constructor

    @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 5xx if this is a snapshot
        return 200;
    }
}

3.11. 啓用所有端點

為了使用 HTTP 訪問 actuator 端點，我們需要同時啓用並暴露它們。

默認情況下，除了 /shutdown 端點，所有端點均已啓用。 只有 /health 和 /info 端點默認被暴露。

我們需要添加以下配置以暴露所有端點：

management.endpoints.web.exposure.include=*

為了明確啓用特定端點（例如 /shutdown），我們使用：

management.endpoint.shutdown.enabled=true

為了暴露所有啓用的端點，除了一個（例如，/loggers），我們使用：

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

3.12. 計劃任務端點

scheduledtasks 端點提供有關應用程序計劃任務的信息，包括其類型、目標和調度信息。

此外，Spring Boot Actuator 暴露了計劃任務的元數據，例如最後執行時間、最後執行狀態和下次執行時間。

我們可以通過向/actuator/scheduledtasks 發送 GET 請求來檢索計劃任務。

$ curl 'http://localhost:8080/actuator/scheduledtasks' -i -X GET

以下是翻譯後的內容：

最終響應與以下內容類似：

{
  "cron": [
    {
      "runnable": {
        "target": "com.baeldung.actuator.JobConfig.scheduleTaskUsingCronExpression"
      },
      "expression": "0 15 10 15 * ?",
      "nextExecution": {
        "time": "2025-01-15T06:45:00.000024100Z"
      }
    }
  ],
  "fixedDelay": [
    {
      "runnable": {
        "target": "com.baeldung.actuator.JobConfig.scheduleFixedDelayTask"
      },
      "initialDelay": 0,
      "interval": 1000,
      "lastExecution": {
        "time": "2024-12-18T15:55:35.273062600Z",
        "status": "SUCCESS"
      },
      "nextExecution": {
        "time": "2024-12-18T15:55:36.272024100Z"
      }
    }
  ],
  "fixedRate": [
    {
      "runnable": {
        "target": "com.baeldung.actuator.JobConfig.scheduleFixedRateTask"
      },
      "initialDelay": 0,
      "interval": 1000,
      "lastExecution": {
        "time": "2024-12-18T15:55:35.162062700Z",
        "status": "SUCCESS"
      },
      "nextExecution": {
        "time": "2024-12-18T15:55:36.160024100Z"
      }
    }
  ],
  "custom": []
}

如我們所見，/actuator/scheduledtasks 端點會暴露有關計劃任務的額外信息。

3.13. SBOM 端點

軟件材料清單 (SBOM) 描述了構建軟件工件所使用的所有組件、庫和依賴項。SBOM 在識別和管理軟件應用程序中的安全漏洞方面發揮着至關重要的作用。

要為 Spring Boot 應用程序生成 SBOM，可以使用諸如 CycloneDX、SPDX 和 Syft 等工具。 Spring Boot 3.3.0 內置了對 CycloneDX 的支持，使其成為生成 SBOM 的便捷選擇。

讓我們首先在 pom.xml 的 <plugins> 部分導入 cyclonedx-maven-plugin 插件：

<plugin>
    <groupId>org.cyclonedx</groupId>
    <artifactId>cyclonedx-maven-plugin</artifactId>
    <executions>
        <execution>
            <phase>generate-resources</phase>
            <goals>
                <goal>makeAggregateBom</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <projectType>application</projectType>
        <outputDirectory>${project.build.outputDirectory}/META-INF/sbom</outputDirectory>
        <outputFormat>json</outputFormat>
        <outputName>application.cdx</outputName>
    </configuration>
</plugin>

Spring Boot 通過其父項目自動管理該插件的版本。

現在，我們運行 mvn package 命令。 在 Maven 構建過程中，Spring Boot 藉助 CycloneDX 插件生成 SBOM，並將 SBOM 包含在創建的 JAR 文件中。 如果我們查看 JAR 的內容，將在 META-INF/sbom/application.cdx.json 中找到 SBOM。

我們還可以通過 actuator 暴露 SBOM 。 為此，我們需要啓用 SBOM actuator 端點，該端點默認未啓用：

management.endpoints.web.exposure.include=sbom

現在，我們準備運行 Spring Boot 應用程序。啓動完成後，我們可以查詢 SBOM 活動端點：

curl http://localhost:8080/actuator/sbom

{"ids":["application"]}

此功能返回所有可用的 SBOM 列表，包括應用程序、JVM、操作系統等。默認情況下，只有一個名為 application 的 SBOM，描述我們的 Spring Boot 應用程序：

curl -i http://localhost:8080/actuator/sbom/application

HTTP/1.1 200
Content-Type: application/vnd.cyclonedx+json
Content-Length: 301209

{
  "bomFormat" : "CycloneDX",
  "specVersion" : "1.5",
  "serialNumber" : "urn:uuid:3842be09-b12e-45ed-8038-babb72a53750",
  "version" : 1,
  ...

在這裏，我們可以看到我們應用程序的內容。它包含有關我們應用程序的所有依賴項的信息，包括它們的哈希值和許可證、網站問題跟蹤器 URL 以及更多內容。

3.14. SSL 捆包指標端點

Spring Boot Actuator 3.5.0-M1 引入了 SSL 指標，用於監控 SSL 捆包，從而實現主動的證書管理。

它提供了兩個關鍵指標用於 SSL 證書監控：ssl.chains 和 ssl.chain.expiry。 這些指標允許我們監控證書健康狀況，並設置自動警報以在證書過期之前續訂證書，從而確保服務不中斷。

要配置 Spring Boot 以啓用 SSL 捆包指標，我們需要啓用 SSL/TLS 並配置證書捆包，在 application.properties 或 application.yml 文件中：

spring.ssl.bundle.jks.server.keystore.location=classpath:ssl/baeldung.p12
spring.ssl.bundle.jks.server.keystore.password=password
spring.ssl.bundle.jks.server.keystore.type=PKCS12

server.ssl.bundle=server
server.ssl.enabled=false

指標 ssl.chains 統計鏈的數量及其狀態（valid, expired, will-expire-soon, not-yet-valid）。

可以通過向 /actuator/metrics/ssl.chains 發送 GET 請求來檢索 ssl.chains：

$ curl 'https://localhost:8080/actuator/metrics/ssl.chains' -i -X GET

{
  "name": "ssl.chains",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 1
    }
  ],
  "availableTags": [
    {
      "tag": "status",
      "values": [
        "valid",
        "not-yet-valid",
        "expired",
        "will-expire-soon"
      ]
    }
  ]
}

測量字段指示鏈的總數（在本例中是1）。狀態標籤列出了可能的狀態，允許按狀態進行過濾。

例如，調用/actuator/metrics/ssl.chains?tag=status:valid來計數有效鏈的響應如下：

{
  "name": "ssl.chains",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 1
    }
  ],
  "availableTags": []
}