端点
Actuator 端点允许您监控应用程序并与其交互。Spring Boot 包含许多内置端点,并允许您添加自己的端点。例如,health 端点提供基本的应用程序健康信息。
您可以控制对每个独立端点的访问,并通过 HTTP 或 JMX 暴露(使其可远程访问)这些端点。当允许访问且已暴露时,端点被认为是可用的。内置端点仅在可用时自动配置。大多数应用程序选择通过 HTTP 暴露,其中端点的 ID 和 /actuator 前缀映射到 URL。例如,默认情况下,health 端点映射到 /actuator/health。
| 要了解有关 Actuator 端点及其请求和响应格式的更多信息,请参阅API 文档。 |
以下与技术无关的端点可用
| ID | 描述 |
|---|---|
|
公开当前应用程序的审计事件信息。需要一个 |
|
显示应用程序中所有 Spring bean 的完整列表。 |
|
公开可用的缓存。 |
|
显示在配置和自动配置类上评估的条件,以及它们匹配或不匹配的原因。 |
|
显示所有 |
|
公开 Spring 的 |
|
显示已应用的任何 Flyway 数据库迁移。需要一个或多个 |
|
显示应用程序健康信息。 |
|
显示 HTTP 交换信息(默认情况下,最后 100 个 HTTP 请求-响应交换)。需要一个 |
|
显示任意应用程序信息。 |
|
显示 Spring Integration 图。需要依赖 |
|
显示和修改应用程序中日志记录器的配置。 |
|
显示已应用的任何 Liquibase 数据库迁移。需要一个或多个 |
|
显示当前应用程序的“度量”信息,以诊断应用程序已记录的度量。 |
|
显示所有 |
|
显示 Quartz 调度器作业的信息。受 清理 约束。 |
|
显示应用程序中的调度任务。 |
|
允许从 Spring Session 支持的会话存储中检索和删除用户会话。需要使用 Spring Session 的基于 servlet 的 Web 应用程序。 |
|
允许应用程序优雅关闭。仅在使用 jar 打包时有效。默认禁用。 |
|
显示 启动步骤数据,这些数据由 |
|
执行线程转储。 |
如果您的应用程序是 Web 应用程序(Spring MVC、Spring WebFlux 或 Jersey),您可以使用以下附加端点
| ID | 描述 |
|---|---|
|
返回堆转储文件。在 HotSpot JVM 上,返回 |
|
返回日志文件内容(如果已设置 |
|
以 Prometheus 服务器可抓取的格式公开指标。需要依赖 |
控制对端点的访问
默认情况下,除 shutdown 和 heapdump 之外的所有端点都可无限制访问。要配置允许访问端点,请使用其 management.endpoint.<id>.access 属性。以下示例允许无限制访问 shutdown 端点
-
属性
-
YAML
management.endpoint.shutdown.access=unrestricted
management:
endpoint:
shutdown:
access: unrestricted
如果您更喜欢选择性加入而不是选择性退出访问,请将 management.endpoints.access.default 属性设置为 none,并使用单独的端点 access 属性选择性加入。以下示例允许对 loggers 端点进行只读访问,并拒绝访问所有其他端点
-
属性
-
YAML
management.endpoints.access.default=none
management.endpoint.loggers.access=read-only
management:
endpoints:
access:
default: none
endpoint:
loggers:
access: read-only
无法访问的端点将完全从应用程序上下文中移除。如果您只想更改端点公开的技术,请使用 include 和 exclude 属性。 |
限制访问
可以使用 management.endpoints.access.max-permitted 属性限制应用程序范围的端点访问。此属性优先于默认访问或单个端点的访问级别。将其设置为 none 以使所有端点都不可访问。将其设置为 read-only 以仅允许对端点进行读取访问。
对于 @Endpoint、@JmxEndpoint 和 @WebEndpoint,读取访问等同于用 @ReadOperation 注解的端点方法。对于 @ControllerEndpoint 和 @RestControllerEndpoint,读取访问等同于可以处理 GET 和 HEAD 请求的请求映射。对于 @ServletEndpoint,读取访问等同于 GET 和 HEAD 请求。
公开端点
默认情况下,只有 health 端点通过 HTTP 和 JMX 公开。由于端点可能包含敏感信息,您应仔细考虑何时公开它们。
要更改公开的端点,请使用以下特定于技术的 include 和 exclude 属性
| 财产 | 默认值 |
|---|---|
|
|
|
|
|
|
|
|
include 属性列出了要公开的端点的 ID。exclude 属性列出了不应公开的端点的 ID。exclude 属性优先于 include 属性。您可以同时使用端点 ID 列表配置 include 和 exclude 属性。
例如,要仅通过 JMX 公开 health 和 info 端点,请使用以下属性
-
属性
-
YAML
management.endpoints.jmx.exposure.include=health,info
management:
endpoints:
jmx:
exposure:
include: "health,info"
* 可用于选择所有端点。例如,要通过 HTTP 公开所有端点,除了 env 和 beans 端点,请使用以下属性
-
属性
-
YAML
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans
management:
endpoints:
web:
exposure:
include: "*"
exclude: "env,beans"
* 在 YAML 中有特殊含义,因此如果要包含(或排除)所有端点,请务必添加引号。 |
| 如果您的应用程序是公开的,我们强烈建议您也保护您的端点。 |
如果您想实现自己的端点公开策略,可以注册一个 EndpointFilter bean。 |
安全
出于安全考虑,默认情况下只有 /health 端点通过 HTTP 公开。您可以使用 management.endpoints.web.exposure.include 属性配置要公开的端点。
在设置 management.endpoints.web.exposure.include 之前,请确保公开的 Actuator 不包含敏感信息,并通过防火墙保护或通过 Spring Security 等方式保护。 |
如果 Spring Security 在类路径中且没有其他 SecurityFilterChain bean,则除 /health 之外的所有 Actuator 都由 Spring Boot 自动配置保护。如果您定义自定义 SecurityFilterChain bean,Spring Boot 自动配置将回退,让您完全控制 Actuator 访问规则。
如果您希望为 HTTP 端点配置自定义安全性(例如,只允许具有特定角色的用户访问它们),Spring Boot 提供了一些方便的 RequestMatcher 对象,您可以将其与 Spring Security 结合使用。
典型的 Spring Security 配置可能如下所示
-
Java
-
Kotlin
import org.springframework.boot.security.autoconfigure.actuate.web.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import static org.springframework.security.config.Customizer.withDefaults;
@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) {
http.securityMatcher(EndpointRequest.toAnyEndpoint());
http.authorizeHttpRequests((requests) -> requests.anyRequest().hasRole("ENDPOINT_ADMIN"));
http.httpBasic(withDefaults());
return http.build();
}
}
import org.springframework.boot.security.autoconfigure.actuate.web.servlet.EndpointRequest
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.Customizer.withDefaults
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.web.SecurityFilterChain
@Configuration(proxyBeanMethods = false)
class MySecurityConfiguration {
@Bean
fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
http.securityMatcher(EndpointRequest.toAnyEndpoint()).authorizeHttpRequests { requests ->
requests.anyRequest().hasRole("ENDPOINT_ADMIN")
}
http.httpBasic(withDefaults())
return http.build()
}
}
前面的示例使用 EndpointRequest.toAnyEndpoint() 匹配对任何端点的请求,然后确保所有请求都具有 ENDPOINT_ADMIN 角色。EndpointRequest 上还提供了其他几个匹配器方法。有关详细信息,请参阅 API 文档。
如果您将应用程序部署在防火墙后面,您可能希望所有 Actuator 端点都可以在不需要身份验证的情况下访问。您可以通过更改 management.endpoints.web.exposure.include 属性来实现,如下所示
-
属性
-
YAML
management.endpoints.web.exposure.include=*
management:
endpoints:
web:
exposure:
include: "*"
此外,如果存在 Spring Security,您需要添加自定义安全配置,允许未经身份验证的用户访问端点,如下例所示
-
Java
-
Kotlin
import org.springframework.boot.security.autoconfigure.actuate.web.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) {
http.securityMatcher(EndpointRequest.toAnyEndpoint());
http.authorizeHttpRequests((requests) -> requests.anyRequest().permitAll());
return http.build();
}
}
import org.springframework.boot.security.autoconfigure.actuate.web.servlet.EndpointRequest
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.web.SecurityFilterChain
@Configuration(proxyBeanMethods = false)
class MySecurityConfiguration {
@Bean
fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
http.securityMatcher(EndpointRequest.toAnyEndpoint()).authorizeHttpRequests { requests ->
requests.anyRequest().permitAll()
}
return http.build()
}
}
在前面的两个示例中,配置仅适用于 Actuator 端点。由于 Spring Boot 的安全配置在存在任何 SecurityFilterChain bean 时完全回退,您需要配置一个额外的 SecurityFilterChain bean,其中包含适用于应用程序其余部分的规则。 |
跨站请求伪造保护
由于 Spring Boot 依赖 Spring Security 的默认值,因此默认情况下启用 CSRF 保护。这意味着,当使用默认安全配置时,需要 POST(关闭和日志记录器端点)、PUT 或 DELETE 的 Actuator 端点会收到 403(禁止)错误。
| 我们建议仅当您创建的服务由非浏览器客户端使用时,才完全禁用 CSRF 保护。 |
您可以在 Spring Security 参考指南 中找到有关 CSRF 保护的更多信息。
配置端点
端点自动缓存对不带任何参数的读取操作的响应。要配置端点缓存响应的时间量,请使用其 cache.time-to-live 属性。以下示例将 beans 端点缓存的生存时间设置为 10 秒
-
属性
-
YAML
management.endpoint.beans.cache.time-to-live=10s
management:
endpoint:
beans:
cache:
time-to-live: "10s"
management.endpoint.<name> 前缀唯一标识正在配置的端点。 |
清理敏感值
/env、/configprops 和 /quartz 端点返回的信息可能是敏感的,因此默认情况下值总是完全清理(替换为 ******)。
仅在以下情况下才能以未清理的形式查看值
-
show-values属性已设置为never以外的值 -
没有自定义
SanitizingFunctionbean 适用
可清理端点的 show-values 属性可以配置为以下值之一
-
never- 值始终完全清理(替换为******) -
always- 值显示给所有用户(只要没有SanitizingFunctionbean 适用) -
when-authorized- 值仅显示给授权用户(只要没有SanitizingFunctionbean 适用)
对于 HTTP 端点,如果用户已通过身份验证并具有端点角色属性配置的角色,则被视为已授权。默认情况下,任何经过身份验证的用户都被授权。
对于 JMX 端点,所有用户始终被授权。
以下示例允许所有具有 admin 角色的用户以原始形式查看 /env 端点中的值。未经授权的用户或没有 admin 角色的用户将只看到已清理的值。
-
属性
-
YAML
management.endpoint.env.show-values=when-authorized
management.endpoint.env.roles=admin
management:
endpoint:
env:
show-values: when-authorized
roles: "admin"
此示例假设尚未定义任何 SanitizingFunction bean。 |
Actuator Web 端点的超媒体
添加了一个“发现页面”,其中包含所有端点的链接。“发现页面”默认在 /actuator 上可用。
要禁用“发现页面”,请将以下属性添加到您的应用程序属性中
-
属性
-
YAML
management.endpoints.web.discovery.enabled=false
management:
endpoints:
web:
discovery:
enabled: false
当配置了自定义管理上下文路径时,“发现页面”会自动从 /actuator 移动到管理上下文的根目录。例如,如果管理上下文路径是 /management,则发现页面可从 /management 获得。当管理上下文路径设置为 / 时,为防止与其他映射冲突的可能性,发现页面将被禁用。
CORS 支持
跨域资源共享 (CORS) 是一种 W3C 规范,允许您灵活地指定授权的跨域请求类型。如果您使用 Spring MVC 或 Spring WebFlux,您可以配置 Actuator 的 Web 端点以支持此类场景。
默认情况下,CORS 支持是禁用的,并且只有在您设置了 management.endpoints.web.cors.allowed-origins 属性后才启用。以下配置允许来自 example.com 域的 GET 和 POST 调用
-
属性
-
YAML
management.endpoints.web.cors.allowed-origins=https://example.com
management.endpoints.web.cors.allowed-methods=GET,POST
management:
endpoints:
web:
cors:
allowed-origins: "https://example.com"
allowed-methods: "GET,POST"
有关选项的完整列表,请参阅 CorsEndpointProperties。 |
JSON
使用 JSON 时,Jackson 用于序列化和反序列化。默认情况下,使用一个独立的 JsonMapper。这种隔离意味着它不与应用程序的 JsonMapper 共享相同的配置,并且不受 spring.jackson.* 属性的影响。要禁用此行为并配置 Actuator 使用应用程序的 JsonMapper,请将 management.endpoints.jackson.isolated-json-mapper 设置为 false。或者,您可以定义自己的 EndpointJsonMapper bean,它生成一个满足您需求的 JsonMapper。Actuator 将使用它进行 JSON 处理。
实现自定义端点
如果您添加一个用 @Bean 注解并用 @Endpoint 注解的 bean,则所有用 @ReadOperation、@WriteOperation 或 @DeleteOperation 注解的方法将自动通过 JMX 公开,在 Web 应用程序中也通过 HTTP 公开。端点可以通过 Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 公开。如果 Jersey 和 Spring MVC 都可用,则使用 Spring MVC。
以下示例公开了一个返回自定义对象的读取操作
-
Java
-
Kotlin
@ReadOperation
public CustomData getData() {
return new CustomData("test", 5);
}
@ReadOperation
fun getData(): CustomData {
return CustomData("test", 5)
}
您还可以通过使用 @JmxEndpoint 或 @WebEndpoint 编写特定于技术的端点。这些端点仅限于各自的技术。例如,@WebEndpoint 仅通过 HTTP 公开,而不通过 JMX 公开。
您可以使用 @EndpointWebExtension 和 @EndpointJmxExtension 编写特定于技术的扩展。这些注解允许您提供特定于技术的操作来增强现有端点。一个端点最多可以有一个每种类型的扩展。
最后,如果您需要访问特定于 Web 框架的功能,您可以实现 servlet 或 Spring @Controller 和 @RestController 端点,代价是它们不能通过 JMX 或在使用不同 Web 框架时使用。
接收输入
端点上的操作通过其参数接收输入。当通过 Web 公开时,这些参数的值从 URL 的查询参数和 JSON 请求正文获取。当通过 JMX 公开时,参数映射到 MBean 操作的参数。默认情况下,参数是必需的。可以通过使用 JSpecify 的 @Nullable 注解使其成为可选。Kotlin 空安全也受支持。
您可以将 JSON 请求正文中的每个根属性映射到端点的参数。考虑以下 JSON 请求正文
{
"name": "test",
"counter": 42
}
您可以使用它来调用一个写入操作,该操作接受 String name 和 int counter 参数,如下例所示
-
Java
-
Kotlin
@WriteOperation
public void updateData(String name, int counter) {
// injects "test" and 42
}
@WriteOperation
fun updateData(name: String?, counter: Int) {
// injects "test" and 42
}
因为端点是技术无关的,所以在方法签名中只能指定简单类型。特别是,不支持声明一个具有 CustomData 类型(定义 name 和 counter 属性)的单个参数。 |
为了让输入映射到操作方法的参数,实现端点的 Java 代码应该用 -parameters 编译。对于 Kotlin 代码,请查阅 Spring Framework 参考中的建议。如果您使用 Spring Boot 的 Gradle 插件或使用 Maven 和 spring-boot-starter-parent,这将自动发生。 |
输入类型转换
传递给端点操作方法的参数(如果需要)会自动转换为所需的类型。在调用操作方法之前,通过 JMX 或 HTTP 接收的输入会使用 ApplicationConversionService 实例以及任何使用 @EndpointConverter 注解的 Converter 或 GenericConverter bean 转换为所需的类型。
自定义 Web 端点
一个 @Endpoint、@WebEndpoint 或 @EndpointWebExtension 上的操作会自动通过 Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 公开。如果 Jersey 和 Spring MVC 都可用,则使用 Spring MVC。
路径
谓词的路径由端点 ID 和 Web 公开端点的基本路径决定。默认基本路径是 /actuator。例如,ID 为 sessions 的端点使用 /actuator/sessions 作为其谓词中的路径。
您可以通过用 @Selector 注解一个或多个操作方法参数来进一步自定义路径。这样的参数作为路径变量添加到路径谓词中。当调用端点操作时,变量的值将传递给操作方法。如果您想捕获所有剩余的路径元素,您可以将 @Selector(Match=ALL_REMAINING) 添加到最后一个参数,并使其成为与 String[] 兼容的类型。
消耗
对于使用请求正文的 @WriteOperation (HTTP POST),谓词的 consumes 子句为 application/vnd.spring-boot.actuator.v2+json, application/json。对于所有其他操作,consumes 子句为空。
生成
谓词的 produces 子句可以通过 @DeleteOperation、@ReadOperation 和 @WriteOperation 注解的 produces 属性来确定。该属性是可选的。如果未使用,则 produces 子句将自动确定。
Web 端点响应状态
端点操作的默认响应状态取决于操作类型(读取、写入或删除)以及操作是否返回值。
如果 @ReadOperation 返回一个值,则响应状态将为 200 (OK)。如果它不返回值,则响应状态将为 404 (Not Found)。
如果 @WriteOperation 或 @DeleteOperation 返回一个值,则响应状态将为 200 (OK)。如果它不返回值,则响应状态将为 204 (No Content)。
如果调用操作时缺少必需参数或参数无法转换为所需类型,则不会调用操作方法,并且响应状态将为 400 (Bad Request)。
Web 端点范围请求
您可以使用 HTTP 范围请求来请求 HTTP 资源的一部分。当使用 Spring MVC 或 Spring Web Flux 时,返回 Resource 的操作会自动支持范围请求。
| 使用 Jersey 时不支持范围请求。 |
Web 端点安全
Web 端点或 Web 特定端点扩展上的操作可以接收当前 Principal 或 SecurityContext 作为方法参数。前者通常与 @Nullable 结合使用,为已认证和未认证用户提供不同的行为。后者通常用于使用其 isUserInRole(String) 方法执行授权检查。
健康信息
您可以使用健康信息来检查运行中应用程序的状态。它通常被监控软件用于在生产系统崩溃时提醒某人。health 端点公开的信息取决于 management.endpoint.health.show-details 和 management.endpoint.health.show-components 属性,这些属性可以配置为以下值之一
| 名称 | 描述 |
|---|---|
|
从不显示详细信息。 |
|
详细信息仅显示给授权用户。授权角色可以使用 |
|
详细信息显示给所有用户。 |
默认值为 never。当用户属于端点的一个或多个角色时,该用户被视为已授权。如果端点没有配置角色(默认),所有已认证用户都被视为已授权。您可以使用 management.endpoint.health.roles 属性配置角色。
如果您已保护您的应用程序并希望使用 always,则您的安全配置必须允许已认证和未经认证的用户访问健康端点。 |
健康信息从 HealthContributorRegistry 的内容收集(默认情况下,您的 ApplicationContext 中定义的所有 HealthContributor 实例)。Spring Boot 包含许多自动配置的 HealthContributor bean,您也可以编写自己的。
一个 HealthContributor 可以是 HealthIndicator 或 CompositeHealthContributor。HealthIndicator 提供实际的健康信息,包括一个 Status。CompositeHealthContributor 提供其他 HealthContributor 实例的组合。总而言之,贡献者形成一个树形结构来表示整体系统健康状况。
默认情况下,最终的系统健康状况由 StatusAggregator 派生,它根据状态的有序列表对每个 HealthIndicator 的状态进行排序。排序列表中的第一个状态用作整体健康状态。如果没有 HealthIndicator 返回 StatusAggregator 已知的状态,则使用 UNKNOWN 状态。
您可以使用 HealthContributorRegistry 在运行时注册和注销健康指示器。 |
自动配置的 HealthIndicators
在适当的情况下,Spring Boot 会自动配置下表中列出的 HealthIndicator bean。您还可以通过配置 management.health.key.enabled 来启用或禁用选定的指示器,其中 key 列在下表中
| 键 | 名称 | 描述 |
|---|---|---|
|
检查 Cassandra 数据库是否正常运行。 |
|
|
检查 Couchbase 集群是否正常运行。 |
|
|
检查是否可以获取到 |
|
|
检查磁盘空间是否不足。 |
|
|
检查 Elasticsearch 集群是否正常运行。 |
|
|
检查 Hazelcast 服务器是否正常运行。 |
|
|
检查 JMS 代理是否正常运行。 |
|
|
检查 LDAP 服务器是否正常运行。 |
|
|
检查邮件服务器是否正常运行。 |
|
|
检查 Mongo 数据库是否正常运行。 |
|
|
检查 Neo4j 数据库是否正常运行。 |
|
|
始终响应 |
|
|
检查 Rabbit 服务器是否正常运行。 |
|
|
检查 Redis 服务器是否正常运行。 |
|
|
检查 SSL 证书是否正常。 |
您可以通过设置 management.health.defaults.enabled 属性来禁用所有这些功能。 |
ssl HealthIndicator 有一个名为 management.health.ssl.certificate-validity-warning-threshold 的“警告阈值”属性。您可以使用此阈值给自己足够的时间来轮换即将过期的证书。如果 SSL 证书在此阈值定义的期限内将失效,HealthIndicator 将在其响应的详细信息部分中报告此情况,其中 details.validChains.certificates.[*].validity.status 将具有值 WILL_EXPIRE_SOON。 |
默认情况下,还启用以下 HealthIndicator bean
| 键 | 名称 | 描述 |
|---|---|---|
|
公开“活跃度”应用程序可用性状态。 |
|
|
公开“就绪度”应用程序可用性状态。 |
这些可以通过使用 management.endpoint.health.probes.enabled 配置属性来禁用。
编写自定义 HealthIndicators
要提供自定义健康信息,您可以注册实现 HealthIndicator 接口的 Spring bean。您需要提供 health() 方法的实现并返回一个 Health 响应。Health 响应应包含一个状态,并且可以选择包含要显示的其他详细信息。以下代码显示了一个示例 HealthIndicator 实现
-
Java
-
Kotlin
import org.springframework.boot.health.contributor.Health;
import org.springframework.boot.health.contributor.HealthIndicator;
import org.springframework.stereotype.Component;
@Component
public class MyHealthIndicator implements HealthIndicator {
@Override
public Health health() {
int errorCode = check();
if (errorCode != 0) {
return Health.down().withDetail("Error Code", errorCode).build();
}
return Health.up().build();
}
private int check() {
// perform some specific health check
return ...
}
}
import org.springframework.boot.health.contributor.Health
import org.springframework.boot.health.contributor.HealthIndicator
import org.springframework.stereotype.Component
@Component
class MyHealthIndicator : HealthIndicator {
override fun health(): Health {
val errorCode = check()
if (errorCode != 0) {
return Health.down().withDetail("Error Code", errorCode).build()
}
return Health.up().build()
}
private fun check(): Int {
// perform some specific health check
return ...
}
}
给定 HealthIndicator 的标识符是 bean 的名称,如果存在,则不带 HealthIndicator 后缀。在前面的示例中,健康信息在名为 my 的条目中可用。 |
健康指标通常通过 HTTP 调用,并且需要在任何连接超时之前响应。对于任何响应时间超过 10 秒的健康指标,Spring Boot 将记录警告消息。如果您想配置此阈值,可以使用 management.endpoint.health.logging.slow-indicator-threshold 属性。 |
除了 Spring Boot 预定义的 Status 类型外,Health 可以返回表示新系统状态的自定义 Status。在这种情况下,您还需要提供 StatusAggregator 接口的自定义实现,或者您必须使用 management.endpoint.health.status.order 配置属性来配置默认实现。
例如,假设您的一个 HealthIndicator 实现中使用了代码为 FATAL 的新 Status。要配置严重性顺序,请将以下属性添加到您的应用程序属性中
-
属性
-
YAML
management.endpoint.health.status.order=fatal,down,out-of-service,unknown,up
management:
endpoint:
health:
status:
order: "fatal,down,out-of-service,unknown,up"
响应中的 HTTP 状态码反映了整体健康状态。默认情况下,OUT_OF_SERVICE 和 DOWN 映射到 503。任何未映射的健康状态,包括 UP,映射到 200。如果您通过 HTTP 访问健康端点,您可能还需要注册自定义状态映射。配置自定义映射会禁用 DOWN 和 OUT_OF_SERVICE 的默认映射。如果您想保留默认映射,则必须明确配置它们以及任何自定义映射。例如,以下属性将 FATAL 映射到 503(服务不可用)并保留 DOWN 和 OUT_OF_SERVICE 的默认映射
-
属性
-
YAML
management.endpoint.health.status.http-mapping.down=503
management.endpoint.health.status.http-mapping.fatal=503
management.endpoint.health.status.http-mapping.out-of-service=503
management:
endpoint:
health:
status:
http-mapping:
down: 503
fatal: 503
out-of-service: 503
如果您需要更多的控制,您可以定义自己的 HttpCodeStatusMapper bean。 |
下表显示了内置状态的默认状态映射
| 状态 | 映射 |
|---|---|
|
|
|
|
|
默认情况下没有映射,因此 HTTP 状态为 |
|
默认情况下没有映射,因此 HTTP 状态为 |
响应式健康指示器
对于响应式应用程序,例如使用 Spring WebFlux 的应用程序,ReactiveHealthContributor 提供了一个非阻塞契约来获取应用程序健康状况。与传统的 HealthContributor 类似,健康信息从 ReactiveHealthContributorRegistry 的内容收集(默认情况下,您的 ApplicationContext 中定义的所有 HealthContributor 和 ReactiveHealthContributor 实例)。不检查响应式 API 的常规 HealthContributor 实例在弹性调度器上执行。
在响应式应用程序中,您应该使用 ReactiveHealthContributorRegistry 在运行时注册和注销健康指示器。如果您需要注册常规的 HealthContributor,您应该将其包装在 ReactiveHealthContributor#adapt 中。 |
要从响应式 API 提供自定义健康信息,您可以注册实现 ReactiveHealthIndicator 接口的 Spring bean。以下代码显示了一个示例 ReactiveHealthIndicator 实现
-
Java
-
Kotlin
import reactor.core.publisher.Mono;
import org.springframework.boot.health.contributor.Health;
import org.springframework.boot.health.contributor.ReactiveHealthIndicator;
import org.springframework.stereotype.Component;
@Component
public class MyReactiveHealthIndicator implements ReactiveHealthIndicator {
@Override
public Mono<Health> health() {
return doHealthCheck().onErrorResume((exception) ->
Mono.just(new Health.Builder().down(exception).build()));
}
private Mono<Health> doHealthCheck() {
// perform some specific health check
return ...
}
}
import org.springframework.boot.health.contributor.Health
import org.springframework.boot.health.contributor.ReactiveHealthIndicator
import org.springframework.stereotype.Component
import reactor.core.publisher.Mono
@Component
class MyReactiveHealthIndicator : ReactiveHealthIndicator {
override fun health(): Mono<Health> {
return doHealthCheck().onErrorResume { exception: Throwable ->
Mono.just(Health.Builder().down(exception).build())
}
}
private fun doHealthCheck(): Mono<Health> {
// perform some specific health check
return ...
}
}
要自动处理错误,请考虑从 AbstractReactiveHealthIndicator 扩展。 |
自动配置的响应式健康指标
在适当的情况下,Spring Boot 会自动配置以下 ReactiveHealthIndicator bean
| 键 | 名称 | 描述 |
|---|---|---|
|
检查 Cassandra 数据库是否正常运行。 |
|
|
检查 Couchbase 集群是否正常运行。 |
|
|
检查 Elasticsearch 集群是否正常运行。 |
|
|
检查 Mongo 数据库是否正常运行。 |
|
|
检查 Neo4j 数据库是否正常运行。 |
|
|
检查 Redis 服务器是否正常运行。 |
如有必要,响应式指示器会替换常规指示器。此外,任何未明确处理的 HealthIndicator 都会自动包装。 |
健康组
有时将健康指示器组织成用于不同目的的组是很有用的。
要创建健康指示器组,可以使用 management.endpoint.health.group.<name> 属性并指定要 include 或 exclude 的健康指示器 ID 列表。例如,要创建一个只包含数据库指示器的组,您可以定义如下
-
属性
-
YAML
management.endpoint.health.group.custom.include=db
management:
endpoint:
health:
group:
custom:
include: "db"
然后您可以通过访问 localhost:8080/actuator/health/custom 来检查结果。
类似地,要创建一个从组中排除数据库指示器并包含所有其他指示器的组,您可以定义如下
-
属性
-
YAML
management.endpoint.health.group.custom.exclude=db
management:
endpoint:
health:
group:
custom:
exclude: "db"
默认情况下,如果健康组包含或排除了不存在的健康指示器,则启动会失败。要禁用此行为,请将 management.endpoint.health.validate-group-membership 设置为 false。
默认情况下,组继承与系统健康相同的 StatusAggregator 和 HttpCodeStatusMapper 设置。但是,您也可以在每个组的基础上定义这些。如果需要,您还可以覆盖 show-details 和 roles 属性
-
属性
-
YAML
management.endpoint.health.group.custom.show-details=when-authorized
management.endpoint.health.group.custom.roles=admin
management.endpoint.health.group.custom.status.order=fatal,up
management.endpoint.health.group.custom.status.http-mapping.fatal=500
management.endpoint.health.group.custom.status.http-mapping.out-of-service=500
management:
endpoint:
health:
group:
custom:
show-details: "when-authorized"
roles: "admin"
status:
order: "fatal,up"
http-mapping:
fatal: 500
out-of-service: 500
如果您需要注册自定义的 StatusAggregator 或 HttpCodeStatusMapper bean 以供组使用,可以使用 @Qualifier("groupname")。 |
健康组还可以包含/排除 CompositeHealthContributor。您还可以只包含/排除 CompositeHealthContributor 的某个组件。这可以通过使用组件的完全限定名称来完成,如下所示
management.endpoint.health.group.custom.include="test/primary"
management.endpoint.health.group.custom.exclude="test/primary/b"
在上面的示例中,custom 组将包含名为 primary 的 HealthContributor,它是复合 test 的一个组件。这里,primary 本身是一个复合,名为 b 的 HealthContributor 将从 custom 组中排除。
健康组可以在主端口或管理端口的附加路径上提供。这在 Kubernetes 等云环境中非常有用,在这些环境中,通常为了安全目的将 Actuator 端点使用单独的管理端口。拥有单独的端口可能会导致不可靠的健康检查,因为即使健康检查成功,主应用程序也可能无法正常工作。健康组可以通过以下方式配置附加路径
management.endpoint.health.group.live.additional-path="server:/healthz"
这将使 live 健康组在主服务器端口的 /healthz 上可用。前缀是强制性的,必须是 server:(表示主服务器端口)或 management:(表示管理端口,如果已配置)。路径必须是单个路径段。
DataSource 健康
DataSource 健康指示器显示标准数据源和路由数据源 bean 的健康状况。路由数据源的健康状况包括其每个目标数据源的健康状况。在健康端点的响应中,路由数据源的每个目标都使用其路由键命名。如果您不希望在指示器的输出中包含路由数据源,请将 management.health.db.ignore-routing-data-sources 设置为 true。
Kubernetes 探针
部署在 Kubernetes 上的应用程序可以通过容器探针提供其内部状态信息。根据您的 Kubernetes 配置,kubelet 会调用这些探针并对结果做出反应。
默认情况下,Spring Boot 管理您的应用程序可用性状态。如果部署在 Kubernetes 环境中,Actuator 会从ApplicationAvailability接口收集“活跃度”和“就绪度”信息,并将这些信息用于专门的健康指示器:LivenessStateHealthIndicator和ReadinessStateHealthIndicator。这些指示器显示在全局健康端点("/actuator/health")上。它们还通过健康组作为单独的 HTTP 探针公开:"/actuator/health/liveness"和"/actuator/health/readiness"。
然后,您可以配置 Kubernetes 基础设施,其中包含以下端点信息
livenessProbe:
httpGet:
path: "/actuator/health/liveness"
port: <actuator-port>
failureThreshold: ...
periodSeconds: ...
readinessProbe:
httpGet:
path: "/actuator/health/readiness"
port: <actuator-port>
failureThreshold: ...
periodSeconds: ...
<actuator-port> 应设置为 Actuator 端点可用的端口。它可以是主 Web 服务器端口,也可以是单独的管理端口(如果已设置 "management.server.port" 属性)。 |
这些健康组会自动启用。您可以通过使用 management.endpoint.health.probes.enabled 配置属性来禁用它们。
如果应用程序启动时间超过配置的活跃度周期,Kubernetes 会提到 "startupProbe" 作为可能的解决方案。一般来说,这里不一定需要 "startupProbe",因为 "readinessProbe" 会一直失败,直到所有启动任务完成。这意味着您的应用程序在准备就绪之前不会接收流量。但是,如果您的应用程序启动时间很长,请考虑使用 "startupProbe" 以确保 Kubernetes 在应用程序启动过程中不会终止它。请参阅描述探针在应用程序生命周期中的行为的部分。 |
如果您的 Actuator 端点部署在单独的管理上下文中,则这些端点不使用与主应用程序相同的 Web 基础设施(端口、连接池、框架组件)。在这种情况下,即使主应用程序无法正常工作(例如,无法接受新连接),探针检查也可能成功。因此,最好在主服务器端口上提供 liveness 和 readiness 健康组。这可以通过设置以下属性来实现
management.endpoint.health.probes.add-additional-paths=true
这将使 liveness 组在主服务器端口的 /livez 上可用,而 readiness 组在 /readyz 上可用。路径可以使用每个组上的 additional-path 属性进行自定义,详细信息请参见健康组。
使用 Kubernetes 探针检查外部状态
Actuator 将“活跃度”和“就绪度”探针配置为健康组。这意味着所有健康组功能都适用于它们。例如,您可以配置额外的健康指示器
-
属性
-
YAML
management.endpoint.health.group.readiness.include=readinessState,customCheck
management:
endpoint:
health:
group:
readiness:
include: "readinessState,customCheck"
默认情况下,Spring Boot 不会向这些组添加其他健康指示器。
“活跃度”探针不应依赖于对外部系统的健康检查。如果应用程序的活跃度状态中断,Kubernetes 会尝试通过重新启动应用程序实例来解决该问题。这意味着如果外部系统(例如数据库、Web API 或外部缓存)发生故障,Kubernetes 可能会重新启动所有应用程序实例并导致级联故障。
至于“就绪度”探针,检查外部系统的选择必须由应用程序开发人员仔细做出。因此,Spring Boot 不会在就绪度探针中包含任何额外的健康检查。如果应用程序实例的就绪度状态未就绪,Kubernetes 不会将流量路由到该实例。某些外部系统可能不被应用程序实例共享,在这种情况下,它们可以包含在就绪度探针中。其他外部系统可能对应用程序不重要(应用程序可能具有断路器和回退),在这种情况下,它们绝对不应该包含在内。不幸的是,所有应用程序实例共享的外部系统很常见,您必须做出判断:将其包含在就绪度探针中并期望当外部服务关闭时应用程序被停止服务,或者将其排除在外并处理堆栈中更高级别的故障,可能通过在调用方中使用断路器。
如果应用程序的所有实例都未就绪,则具有 type=ClusterIP 或 NodePort 的 Kubernetes Service 不会接受任何传入连接。没有 HTTP 错误响应(503 等),因为没有连接。具有 type=LoadBalancer 的服务可能会或可能不会接受连接,具体取决于提供商。具有显式 ingress 的服务也以取决于实现的方式响应——ingress 服务本身必须决定如何处理来自下游的“连接拒绝”。在负载均衡器和 ingress 的情况下,HTTP 503 很可能发生。 |
此外,如果应用程序使用 Kubernetes 自动扩缩,它可能会对应用程序从负载均衡器中移除做出不同的反应,具体取决于其自动扩缩器配置。
应用程序生命周期和探针状态
Kubernetes 探针支持的一个重要方面是它与应用程序生命周期的一致性。 AvailabilityState(即应用程序的内存内部状态)与实际探针(即公开该状态)之间存在显著差异。根据应用程序生命周期的阶段,探针可能不可用。
Spring Boot 在启动和关闭期间发布应用程序事件,探针可以监听此类事件并公开 AvailabilityState 信息。
下表显示了在不同阶段的 AvailabilityState 和 HTTP 连接器状态。
当 Spring Boot 应用程序启动时
| 启动阶段 | LivenessState | ReadinessState | HTTP 服务器 | 备注 |
|---|---|---|---|---|
启动中 |
|
|
未启动 |
Kubernetes 检查“活跃度”探针,如果应用程序耗时过长,则重新启动应用程序。 |
已启动 |
|
|
拒绝请求 |
应用程序上下文已刷新。应用程序执行启动任务,但尚未接收流量。 |
就绪 |
|
|
接受请求 |
启动任务已完成。应用程序正在接收流量。 |
当 Spring Boot 应用程序关闭时
| 关闭阶段 | 活跃度状态 | 就绪度状态 | HTTP 服务器 | 备注 |
|---|---|---|---|---|
运行中 |
|
|
接受请求 |
已请求关闭。 |
优雅关闭 |
|
|
新请求被拒绝 |
如果启用,优雅关闭会处理正在进行的请求。 |
关闭完成 |
不适用 |
不适用 |
服务器已关闭 |
应用程序上下文已关闭,应用程序已停止。 |
| 有关 Kubernetes 部署的更多信息,请参阅 Kubernetes 容器生命周期。 |
应用程序信息
应用程序信息公开从您的 ApplicationContext 中定义的所有 InfoContributor bean 收集的各种信息。Spring Boot 包含许多自动配置的 InfoContributor bean,您也可以编写自己的。
自动配置的 InfoContributors
在适当的时候,Spring 会自动配置以下 InfoContributor bean
| ID | 名称 | 描述 | 先决条件 |
|---|---|---|---|
|
公开构建信息。 |
一个 |
|
|
公开 |
无。 |
|
|
公开 git 信息。 |
一个 |
|
|
公开 Java 运行时信息。 |
无。 |
|
|
公开操作系统信息。 |
无。 |
|
|
公开进程信息。 |
无。 |
|
|
公开 SSL 证书信息。 |
已配置 SSL 捆绑包。 |
每个贡献者是否启用由其 management.info.<id>.enabled 属性控制。不同的贡献者对此属性有不同的默认值,具体取决于它们的先决条件和它们公开的信息的性质。
由于没有先决条件表明它们应该被启用,env、java、os 和 process 贡献者默认是禁用的。ssl 贡献者有一个配置 SSL Bundle 的先决条件,但默认是禁用的。每个都可以通过将其 management.info.<id>.enabled 属性设置为 true 来启用。
build 和 git 信息贡献者默认启用。可以通过将其 management.info.<id>.enabled 属性设置为 false 来禁用它们。或者,要禁用所有通常默认启用的贡献者,请将 management.info.defaults.enabled 属性设置为 false。
自定义应用程序信息
当 env 贡献者启用时,您可以通过设置 info.* Spring 属性来定制 info 端点公开的数据。Environment 键下所有 info 的属性都会自动公开。例如,您可以将以下设置添加到您的 application.properties 文件中
-
属性
-
YAML
info.app.encoding=UTF-8
info.app.java.source=17
info.app.java.target=17
info:
app:
encoding: "UTF-8"
java:
source: "17"
target: "17"
|
您也可以在构建时扩展 info 属性,而不是硬编码这些值。 假设您使用 Maven,您可以将前面的示例改写为
|
Git 提交信息
info 端点的另一个有用功能是它能够在项目构建时发布有关 git 源代码存储库状态的信息。如果 GitProperties bean 可用,您可以使用 info 端点来公开这些属性。
如果类路径根目录中存在 git.properties 文件,则会自动配置一个 GitProperties bean。有关详细信息,请参阅生成 Git 信息。 |
默认情况下,如果存在,端点会公开 git.branch、git.commit.id 和 git.commit.time 属性。如果您不希望这些属性中的任何一个出现在端点响应中,则需要将它们从 git.properties 文件中排除。如果您想显示完整的 git 信息(即 git.properties 的完整内容),请使用 management.info.git.mode 属性,如下所示
-
属性
-
YAML
management.info.git.mode=full
management:
info:
git:
mode: "full"
要完全禁用 info 端点的 git 提交信息,请将 management.info.git.enabled 属性设置为 false,如下所示
-
属性
-
YAML
management.info.git.enabled=false
management:
info:
git:
enabled: false
构建信息
如果 BuildProperties bean 可用,info 端点也可以发布有关您的构建的信息。如果类路径中存在 META-INF/build-info.properties 文件,就会发生这种情况。
| Maven 和 Gradle 插件都可以生成该文件。有关更多详细信息,请参阅生成构建信息。 |
Java 信息
info 端点发布有关您的 Java 运行时环境的信息,有关更多详细信息,请参见 JavaInfo。
操作系统信息
info 端点发布有关您的操作系统的信息,有关更多详细信息,请参见 OsInfo。
进程信息
info 端点发布有关您的进程的信息,有关更多详细信息,请参见 ProcessInfo。
编写自定义 InfoContributors
要提供自定义应用程序信息,您可以注册实现 InfoContributor 接口的 Spring bean。
以下示例提供了一个包含单个值的 example 条目
-
Java
-
Kotlin
import java.util.Collections;
import org.springframework.boot.actuate.info.Info;
import org.springframework.boot.actuate.info.InfoContributor;
import org.springframework.stereotype.Component;
@Component
public class MyInfoContributor implements InfoContributor {
@Override
public void contribute(Info.Builder builder) {
builder.withDetail("example", Collections.singletonMap("key", "value"));
}
}
import org.springframework.boot.actuate.info.Info
import org.springframework.boot.actuate.info.InfoContributor
import org.springframework.stereotype.Component
import java.util.Collections
@Component
class MyInfoContributor : InfoContributor {
override fun contribute(builder: Info.Builder) {
builder.withDetail("example", Collections.singletonMap("key", "value"))
}
}
如果您访问 info 端点,您应该会看到包含以下附加条目的响应
{
"example": {
"key" : "value"
}
}
软件物料清单 (SBOM)
sbom 端点公开软件物料清单。CycloneDX SBOMs 可以自动检测,但也可以手动配置其他格式。
sbom Actuator 端点将公开一个名为“application”的 SBOM,它描述了您的应用程序的内容。
| 要自动在项目构建时生成 CycloneDX SBOM,请参阅生成 CycloneDX SBOM 部分。 |
其他 SBOM 格式
如果您想发布不同格式的 SBOM,可以使用一些配置属性。
配置属性 management.endpoint.sbom.application.location 设置应用程序 SBOM 的位置。例如,将其设置为 classpath:sbom.json 将使用类路径上 /sbom.json 资源的内容。
CycloneDX、SPDX 和 Syft 格式的 SBOM 的媒体类型会自动检测。要覆盖自动检测的媒体类型,请使用配置属性 management.endpoint.sbom.application.media-type。
附加 SBOMs
Actuator 端点可以处理多个 SBOM。要添加 SBOM,请使用配置属性 management.endpoint.sbom.additional,如本例所示
-
属性
-
YAML
management.endpoint.sbom.additional.system.location=optional:file:/system.spdx.json
management.endpoint.sbom.additional.system.media-type=application/spdx+json
management:
endpoint:
sbom:
additional:
system:
location: "optional:file:/system.spdx.json"
media-type: "application/spdx+json"
这将添加一个名为“system”的 SBOM,它存储在 /system.spdx.json 中。可以使用 optional: 前缀来防止文件不存在时启动失败。