此版本仍在开发中,尚未被视为稳定版本。对于最新的稳定版本,请使用 Spring Boot 3.4.0! |
端点
Actuator 终端节点允许您监控应用程序并与之交互。
Spring Boot 包含许多内置端点,并允许您添加自己的端点。
例如,终端节点提供基本的应用程序运行状况信息。health
您可以启用或禁用每个单独的终端节点,并通过 HTTP 或 JMX 公开它们(使其可远程访问)。
当终端节点同时启用和公开时,该终端节点被视为可用。
仅当内置终端节点可用时,才会自动配置这些终端节点。
大多数应用程序选择通过 HTTP 进行公开,其中终端节点的 ID 和前缀映射到 URL。
例如,默认情况下,端点映射到 ./actuator
health
/actuator/health
要了解有关 Actuator 的终端节点及其请求和响应格式的更多信息,请参阅 API 文档。 |
以下与技术无关的终端节点可用:
身份证 | 描述 |
---|---|
|
公开当前应用程序的审计事件信息。
需要 |
|
显示应用程序中所有 Spring bean 的完整列表。 |
|
公开可用的缓存。 |
|
显示在 configuration 和 auto-configuration 类上评估的条件,以及它们匹配或不匹配的原因。 |
|
显示所有 |
|
公开 Spring 的 |
|
显示已应用的任何 Flyway 数据库迁移。
需要一个或多个 |
|
显示应用程序运行状况信息。 |
|
显示 HTTP 交换信息(默认情况下,最后 100 个 HTTP 请求-响应交换)。
需要 |
|
显示任意应用程序信息。 |
|
显示 Spring 集成图。
需要依赖 。 |
|
显示和修改应用程序中记录器的配置。 |
|
显示已应用的任何 Liquibase 数据库迁移。
需要一个或多个 |
|
显示当前应用程序的 “metrics” 信息。 |
|
显示所有 |
|
显示有关 Quartz Scheduler 作业的信息。 需进行消毒。 |
|
显示应用程序中的计划任务。 |
|
允许从 Spring Session 支持的会话存储中检索和删除用户会话。 需要使用 Spring Session 的基于 servlet 的 Web 应用程序。 |
|
允许正常关闭应用程序。 仅在使用 jar 打包时有效。 默认处于禁用状态。 |
|
显示 |
|
执行线程转储。 |
如果您的应用程序是 Web 应用程序(Spring MVC、Spring WebFlux 或 Jersey),则可以使用以下附加端点:
身份证 | 描述 |
---|---|
|
返回堆转储文件。
在 HotSpot JVM 上,将返回 -format 文件。
在 OpenJ9 JVM 上,将返回 -format 文件。 |
|
返回日志文件的内容(如果已设置 or 属性)。
支持使用 HTTP 标头检索日志文件的部分内容。 |
|
以 Prometheus 服务器可抓取的格式公开指标。
需要依赖 。 |
启用终端节点
默认情况下,除 之外的所有端点都处于启用状态。
要配置端点的启用,请使用其属性。
以下示例启用终端节点:shutdown
management.endpoint.<id>.enabled
shutdown
-
Properties
-
YAML
management.endpoint.shutdown.enabled=true
management:
endpoint:
shutdown:
enabled: true
如果您希望终端节点启用选择加入而不是选择退出,请将该属性设置为并使用单个终端节点属性来选择重新加入。
以下示例启用终端节点并禁用所有其他终端节点:management.endpoints.enabled-by-default
false
enabled
info
-
Properties
-
YAML
management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true
management:
endpoints:
enabled-by-default: false
endpoint:
info:
enabled: true
已禁用的端点将从应用程序上下文中完全删除。
如果只想更改公开端点的技术,请改用 include 和 exclude 属性。 |
公开端点
默认情况下,仅通过 HTTP 和 JMX 公开运行状况终端节点。 由于 Endpoints 可能包含敏感信息,因此您应该仔细考虑何时公开它们。
要更改公开的终端节点,请使用以下特定于技术的 and 属性:include
exclude
财产 | 违约 |
---|---|
|
|
|
|
|
|
|
|
该属性列出了公开的终端节点的 ID。
该属性列出了不应公开的端点的 ID。
该属性优先于该属性。
您可以使用终端节点 ID 列表配置 和 属性。include
exclude
exclude
include
include
exclude
例如,要仅通过 JMX 公开 and 端点,请使用以下属性:health
info
-
Properties
-
YAML
management.endpoints.jmx.exposure.include=health,info
management:
endpoints:
jmx:
exposure:
include: "health,info"
*
可用于选择所有端点。
例如,要通过 HTTP 公开除 和 endpoints 之外的所有内容,请使用以下属性:env
beans
-
Properties
-
YAML
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans
management:
endpoints:
web:
exposure:
include: "*"
exclude: "env,beans"
* 在 YAML 中具有特殊含义,因此如果要包含(或排除)所有终端节点,请务必添加引号。 |
如果您的应用程序公开,我们强烈建议您同时保护终端节点。 |
如果要在公开端点时实现自己的策略,则可以注册一个 EndpointFilter Bean。 |
安全
出于安全考虑,默认情况下,仅通过 HTTP 公开终端节点。
您可以使用该属性来配置公开的终端节点。/health
management.endpoints.web.exposure.include
在设置之前,请确保公开的 actuator 不包含敏感信息,通过将它们放置在防火墙后面进行保护,或者由 Spring Security 之类的东西进行保护。management.endpoints.web.exposure.include |
如果 Spring Security 在 Classpath 上并且不存在其他SecurityFilterChain
bean,则除 Spring Boot 自动配置之外的所有执行器都受到保护。
如果你定义了一个自定义的SecurityFilterChain
bean,Spring Boot 自动配置将退缩,并允许你完全控制执行器访问规则。/health
如果你希望为 HTTP 端点配置自定义安全性(例如,只允许具有特定角色的用户访问它们),Spring Boot 提供了一些方便的RequestMatcher
对象,你可以将这些对象与 Spring Security 结合使用。
典型的 Spring Security 配置可能类似于以下示例:
-
Java
-
Kotlin
import org.springframework.boot.actuate.autoconfigure.security.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) throws Exception {
http.securityMatcher(EndpointRequest.toAnyEndpoint());
http.authorizeHttpRequests((requests) -> requests.anyRequest().hasRole("ENDPOINT_ADMIN"));
http.httpBasic(withDefaults());
return http.build();
}
}
import org.springframework.boot.actuate.autoconfigure.security.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
上还提供了其他几种匹配器方法。
有关详细信息,请参阅 API 文档。EndpointRequest.toAnyEndpoint()
ENDPOINT_ADMIN
如果您在防火墙后面部署应用程序,您可能希望无需身份验证即可访问所有 actuator 终端节点。
您可以通过更改属性来执行此操作,如下所示:management.endpoints.web.exposure.include
-
Properties
-
YAML
management.endpoints.web.exposure.include=*
management:
endpoints:
web:
exposure:
include: "*"
此外,如果存在 Spring Security,则需要添加自定义安全配置,以允许对端点进行未经身份验证的访问,如下例所示:
-
Java
-
Kotlin
import org.springframework.boot.actuate.autoconfigure.security.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) throws Exception {
http.securityMatcher(EndpointRequest.toAnyEndpoint());
http.authorizeHttpRequests((requests) -> requests.anyRequest().permitAll());
return http.build();
}
}
import org.springframework.boot.actuate.autoconfigure.security.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 保护默认处于打开状态。
这意味着在使用默认安全配置时,需要 (shutdown 和 loggers endpoints s)、a 或 a 的 actuator endpoints 会出现 403 (forbidden) 错误。POST
PUT
DELETE
我们建议仅在您创建的服务由非浏览器客户端使用时才完全禁用 CSRF 保护。 |
您可以在 Spring Security 参考指南中找到有关 CSRF 保护的其他信息。
配置端点
终端节点会自动缓存对不采用任何参数的读取操作的响应。
要配置终端节点缓存响应的时间量,请使用其属性。
以下示例将终端节点缓存的生存时间设置为 10 秒:cache.time-to-live
beans
-
Properties
-
YAML
management.endpoint.beans.cache.time-to-live=10s
management:
endpoint:
beans:
cache:
time-to-live: "10s"
前缀唯一标识正在配置的终端节点。management.endpoint.<name> |
清理敏感值
和 endpoints 返回的信息可能是敏感的,因此默认情况下,值始终被完全清理(替换为)。/env
/configprops
/quartz
******
只有在以下情况下,才能以未经清理的形式查看值:
-
该属性已设置为非
show-values
NEVER
-
没有自定义
SanitizingFunction
bean 适用
可以将可清理终端节点的属性配置为以下值之一:show-values
-
never
- 值始终被完全清理(替换为******
) -
always
- 向所有用户显示值(只要没有SanitizingFunction
bean 适用) -
when-authorized
- 值仅向授权用户显示(只要没有SanitizingFunction
bean 适用)
对于 HTTP 端点,如果用户已经过身份验证并且角色由端点的 roles 属性配置,则认为该用户已获得授权。 默认情况下,任何经过身份验证的用户都已获得授权。
对于 JMX 终端节点,所有用户始终获得授权。
以下示例允许具有该角色的所有用户以原始格式查看终端节点中的值。
未经授权的用户或没有该角色的用户将只能看到经过清理的值。admin
/env
admin
-
Properties
-
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
要禁用“发现页面”,请将以下属性添加到您的应用程序属性中:
-
Properties
-
YAML
management.endpoints.web.discovery.enabled=false
management:
endpoints:
web:
discovery:
enabled: false
配置自定义管理上下文路径后,“发现页面” 会自动从管理上下文移动到根目录。
例如,如果管理上下文路径为 ,则可从 获取发现页面。
当 Management context path 设置为 时,将禁用发现页面,以防止与其他映射发生冲突。/actuator
/management
/management
/
CORS 支持
跨域资源共享 (CORS) 是一种 W3C 规范,可让您以灵活的方式指定授权的跨域请求类型。 如果您使用 Spring MVC 或 Spring WebFlux,则可以配置 Actuator 的 Web 端点以支持此类场景。
CORS 支持默认处于禁用状态,并且仅在您设置了属性后才会启用。
以下配置允许和调用来自域:management.endpoints.web.cors.allowed-origins
GET
POST
example.com
-
Properties
-
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 。 |
实现自定义端点
如果添加使用 @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 操作的参数。
默认情况下,参数是必需的。
可以通过使用 OR @Nullable
注释它们来使它们成为可选的。@javax.annotation.Nullable
您可以将 JSON 请求正文中的每个根属性映射到终端节点的参数。 请考虑以下 JSON 请求正文:
{
"name": "test",
"counter": 42
}
您可以使用它来调用采用 and parameters 的写入操作,如下例所示: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
}
由于端点与技术无关,因此只能在方法签名中指定简单类型。
具体而言,不支持使用定义 a 和 properties 的 CustomData 类型声明单个参数。name counter |
要使输入映射到操作方法的参数,应使用 编译实现端点的 Java 代码,并使用 编译实现端点的 Kotlin 代码。
如果您使用 Spring Boot 的 Gradle 插件,或者如果您使用 Maven 和 .-parameters -java-parameters spring-boot-starter-parent |
输入类型转换
如有必要,传递给终端节点操作方法的参数会自动转换为所需的类型。
在调用操作方法之前,通过使用ApplicationConversionService
的实例以及使用@EndpointConverter
限定的任何Converter或GenericConverter
bean,将通过 JMX 或 HTTP 接收的 Importing
转换为所需的类型。
自定义 Web 终端节点
对 @Endpoint
、@WebEndpoint
或 @EndpointWebExtension
的操作使用 Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 自动公开。
如果 Jersey 和 Spring MVC 都可用,则使用 Spring MVC。
路径
谓词的路径由终端节点的 ID 和 Web 公开的终端节点的基本路径确定。
默认基本路径为 .
例如,ID 为 uses 作为其在谓词中的路径的终端节点。/actuator
sessions
/actuator/sessions
您可以通过使用 @Selector
注释操作方法的一个或多个参数来进一步自定义路径。
此类参数将作为 path 变量添加到 path 谓词中。
调用 endpoint 操作时,变量的值将传递到 operation 方法中。
如果要捕获所有剩余的路径元素,可以添加到最后一个参数,并使其成为与 .@Selector(Match=ALL_REMAINING)
String[]
消耗
对于使用请求正文的 @WriteOperation
(HTTP ),谓词的子句为 。
对于所有其他操作,子句为空。POST
consumes
application/vnd.spring-boot.actuator.v2+json, application/json
consumes
生产
谓词的子句可以由 @DeleteOperation
、@ReadOperation
和 @WriteOperation
注释的属性确定。
该属性是可选的。
如果未使用,则自动确定子句。produces
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
作为方法参数。
前者通常与 OR @Nullable
结合使用,以便为经过身份验证和未经身份验证的用户提供不同的行为。
后者通常用于使用其方法执行授权检查。@javax.annotation.Nullable
isUserInRole(String)
健康信息
您可以使用运行状况信息来检查正在运行的应用程序的状态。
监控软件经常使用它来在生产系统出现故障时提醒某人。
端点公开的信息取决于 和 属性,这些属性可以使用以下值之一进行配置:health
management.endpoint.health.show-details
management.endpoint.health.show-components
名字 | 描述 |
---|---|
|
详细信息永远不会显示。 |
|
详细信息仅向授权用户显示。
可以使用 配置授权角色。 |
|
详细信息将向所有用户显示。 |
默认值为 .
当用户处于终端节点的一个或多个角色中时,即被视为已获得授权。
如果终端节点没有配置角色(默认),则所有经过身份验证的用户都被视为已获得授权。
您可以使用 property 配置角色。never
management.endpoint.health.roles
如果您已保护应用程序并希望使用 ,则您的安全配置必须允许经过身份验证和未经身份验证的用户访问 health 端点。always |
健康信息是从 HealthContributorRegistry
的内容中收集的(默认情况下,在 ApplicationContext
中定义的所有 HealthContributor
实例)。
Spring Boot 包含许多自动配置的HealthContributor
bean,您也可以编写自己的 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 服务器是否已启动。 |
|
|
检查 InfluxDB 服务器是否已启动。 |
|
|
检查 JMS 代理是否已启动。 |
|
|
检查 LDAP 服务器是否已启动。 |
|
|
检查邮件服务器是否已启动。 |
|
|
检查 Mongo 数据库是否已启动。 |
|
|
检查 Neo4j 数据库是否已启动。 |
|
|
始终以 . |
|
|
检查 Rabbit 服务器是否已启动。 |
|
|
检查 Redis 服务器是否已启动。 |
您可以通过设置属性来禁用它们。management.health.defaults.enabled |
其他 HealthIndicator
bean 可用,但默认情况下不启用:
钥匙 | 名字 | 描述 |
---|---|---|
|
公开 “Liveness” 应用程序可用性状态。 |
|
|
公开 “Readiness” 应用程序可用性状态。 |
编写自定义 HealthIndicators
要提供自定义运行状况信息,您可以注册实现 HealthIndicator
接口的 Spring bean。
您需要提供该方法的实现并返回 Health
响应。
的 Health
响应应包含状态,并且可以选择包含要显示的其他详细信息。
以下代码显示了一个示例 HealthIndicator
实现:health()
-
Java
-
Kotlin
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.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.actuate.health.Health
import org.springframework.boot.actuate.health.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 的标识符是不带 HealthIndicator 后缀的 bean 的名称(如果存在)。
在前面的示例中,运行状况信息在名为 .my |
运行状况指示器通常通过 HTTP 调用,并且需要在任何连接超时之前做出响应。
Spring Boot 将记录一条警告消息,用于响应时间超过 10 秒的任何运行状况指示器。
如果要配置此阈值,可以使用 property .management.endpoint.health.logging.slow-indicator-threshold |
除了 Spring Boot 的预定义 Status
类型之外,Health
还可以返回表示新系统状态的自定义Status
。
在这种情况下,您还需要提供 StatusAggregator
接口的自定义实现,或者必须使用 configuration 属性配置默认实现。management.endpoint.health.status.order
例如,假设代码为 的新 Status
正在您的某个 HealthIndicator
实现中使用。
要配置严重性顺序,请将以下属性添加到您的应用程序属性中:FATAL
-
Properties
-
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 状态代码反映了整体运行状况。
默认情况下,映射到 503。
任何未映射的运行状况(包括 )都映射到 200。
如果您通过 HTTP 访问运行状况终端节点,您可能还需要注册自定义状态映射。
配置自定义映射将禁用 和 的默认映射。
如果要保留默认映射,则必须显式配置它们以及任何自定义映射。
例如,以下属性映射到 503(服务不可用)并保留 和 的默认映射:OUT_OF_SERVICE
DOWN
UP
DOWN
OUT_OF_SERVICE
FATAL
DOWN
OUT_OF_SERVICE
-
Properties
-
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
提供了一个非阻塞 Contract 来获取应用程序运行状况。
与传统的HealthContributor
类似,健康信息是从ReactiveHealthContributorRegistry
的内容中收集的(默认情况下,在ApplicationContext
中定义的所有HealthContributor
和ReactiveHealthContributor
实例)。
不检查反应式 API 的常规 HealthContributor
实例在 Elastic 调度器上执行。
在响应式应用程序中,您应该使用 ReactiveHealthContributorRegistry 在运行时注册和注销健康指标。
如果需要注册常规 HealthContributor ,则应将其包装为 .ReactiveHealthContributor#adapt |
要从反应式 API 提供自定义运行状况信息,你可以注册实现ReactiveHealthIndicator
接口的 Spring bean。
以下代码显示了一个示例 ReactiveHealthIndicator
实现:
-
Java
-
Kotlin
import reactor.core.publisher.Mono;
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.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.actuate.health.Health
import org.springframework.boot.actuate.health.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 扩展。 |
自动配置的 ReactiveHealthIndicators
在适当的时候, Spring Boot 会自动配置以下ReactiveHealthIndicator
bean:
钥匙 | 名字 | 描述 |
---|---|---|
|
检查 Cassandra 数据库是否已启动。 |
|
|
检查 Couchbase 集群是否已启动。 |
|
|
检查 Elasticsearch 集群是否已启动。 |
|
|
检查 Mongo 数据库是否已启动。 |
|
|
检查 Neo4j 数据库是否已启动。 |
|
|
检查 Redis 服务器是否已启动。 |
如有必要,反应式指标将替换常规指标。
此外,任何未明确处理的 HealthIndicator 都会自动包装。 |
健康组
有时,将运行状况指示器组织到可用于不同目的的组中非常有用。
要创建运行状况指示器组,可以使用 该属性并将运行状况指示器 ID 列表指定到 或 。
例如,要创建仅包含数据库指示器的组,您可以定义以下内容:management.endpoint.health.group.<name>
include
exclude
-
Properties
-
YAML
management.endpoint.health.group.custom.include=db
management:
endpoint:
health:
group:
custom:
include: "db"
然后,您可以通过点击 来检查结果。localhost:8080/actuator/health/custom
同样,要创建一个从组中排除数据库指标并包括所有其他指标的组,您可以定义以下内容:
-
Properties
-
YAML
management.endpoint.health.group.custom.exclude=db
management:
endpoint:
health:
group:
custom:
exclude: "db"
默认情况下,如果运行状况组包含或排除不存在的运行状况指示器,则启动将失败。
要禁用此行为,请将 .management.endpoint.health.validate-group-membership
false
默认情况下,组继承与系统运行状况相同的 StatusAggregator
和 HttpCodeStatusMapper
设置。
但是,您也可以按组定义这些 ID。
如果需要,您还可以覆盖 and 属性:show-details
roles
-
Properties
-
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"
在上面的示例中,该组将包含名称为 Composite 的 HealthContributor
。
此处,它本身是一个复合函数,具有该名称的 HealthContributor
将从组中排除。custom
primary
test
primary
b
custom
运行状况组可以在主端口或管理端口上的其他路径上可用。 这在 Kubernetes 等云环境中很有用,出于安全目的,为 actuator 端点使用单独的 management 端口是很常见的。 拥有单独的端口可能会导致运行状况检查不可靠,因为即使运行状况检查成功,主应用程序也可能无法正常工作。 运行状况组可以配置其他路径,如下所示:
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 上的应用程序可以通过 Container Probe 提供有关其内部状态的信息。 根据您的 Kubernetes 配置,kubelet 会调用这些探测并对结果做出反应。
默认情况下, Spring Boot 管理您的应用程序可用性状态。
如果部署在 Kubernetes 环境中,执行器会从 ApplicationAvailability
接口收集“Liveness”和“Readiness”信息,并在专用的健康指标中使用该信息:LivenessStateHealthIndicator
和 ReadinessStateHealthIndicator
。
这些指示器显示在全局运行状况终端节点 () 上。
它们还通过使用运行状况组作为单独的 HTTP 探测公开:和 ."/actuator/health"
"/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 endpoints 可用的端口。
它可以是主 Web 服务器端口,也可以是单独的管理端口(如果已设置该属性)。"management.server.port" |
仅当应用程序在 Kubernetes 环境中运行时,才会自动启用这些运行状况组。
您可以使用 configuration 属性在任何环境中启用它们。management.endpoint.health.probes.enabled
如果应用程序的启动时间超过配置的活跃期,Kubernetes 会提到 这是可能的解决方案。
一般来说,这里不一定需要 the,因为 在完成所有启动任务之前 都会失败。
这意味着您的应用程序在准备就绪之前不会接收流量。
但是,如果您的应用程序需要很长时间才能启动,请考虑使用 a 来确保 Kubernetes 不会在启动过程中终止您的应用程序。
请参阅描述 Probe 在应用程序生命周期中的行为方式的部分。"startupProbe" "startupProbe" "readinessProbe" "startupProbe" |
如果您的 Actuator 端点部署在单独的 Management 上下文中,则端点不会使用与主应用程序相同的 Web 基础架构(端口、连接池、框架组件)。
在这种情况下,即使主应用程序无法正常工作(例如,它无法接受新连接),探测检查也可能成功。
因此,最好在主服务器端口上提供 和 运行状况组。
这可以通过设置以下属性来完成:liveness
readiness
management.endpoint.health.probes.add-additional-paths=true
这将使组在 和 组在主服务器端口上可用。
可以使用每个组上的属性自定义路径,有关详细信息,请参阅运行状况组。liveness
/livez
readiness
/readyz
additional-path
使用 Kubernetes 探针检查外部状态
Actuator 将 “liveness” 和 “readiness” 探针配置为 Health Group。 这意味着所有运行状况组功能都可供他们使用。 例如,您可以配置其他运行状况指示器:
-
Properties
-
YAML
management.endpoint.health.group.readiness.include=readinessState,customCheck
management:
endpoint:
health:
group:
readiness:
include: "readinessState,customCheck"
默认情况下, Spring Boot 不会向这些组添加其他运行状况指示器。
“活动性” 探测不应依赖于外部系统的运行状况检查。 如果应用程序的活跃状态被破坏,Kubernetes 会尝试通过重启应用程序实例来解决这个问题。 这意味着,如果外部系统(例如数据库、Web API 或外部缓存)发生故障,Kubernetes 可能会重新启动所有应用程序实例并产生级联故障。
至于 “readiness” 探测,应用程序开发人员必须仔细选择检查外部系统。 因此, Spring Boot 在就绪情况探测中不包括任何其他运行状况检查。 如果应用程序实例的就绪状态为 unready,Kubernetes 不会将流量路由到该实例。 某些外部系统可能不由应用程序实例共享,在这种情况下,它们可能包含在就绪情况探测中。 其他外部系统对于应用程序可能不是必需的(应用程序可能具有断路器和回退),在这种情况下,它们绝对不应包含在内。 不幸的是,所有应用程序实例共享的外部系统是通用的,您必须做出判断:将其包含在就绪情况探测中,并期望当外部服务关闭时应用程序会停止服务,或者将其排除在外,并处理堆栈上层的故障,也许是在调用者中使用断路器。
如果应用程序的所有实例都未就绪,则具有或不接受任何传入连接的 Kubernetes Service。
没有 HTTP 错误响应(503 等),因为没有连接。
服务可能接受也可能不接受连接,具体取决于提供商。
具有显式 Ingress 的服务也以取决于实现的方式进行响应 — Ingress 服务本身必须决定如何处理来自下游的 “connection refused”。
HTTP 503 在负载均衡器和入口的情况下都很可能出现。type=ClusterIP NodePort type=LoadBalancer |
此外,如果应用程序使用 Kubernetes 自动扩展,则它可能会对从负载均衡器中取出的应用程序做出不同的反应,具体取决于其自动扩展器配置。
应用程序生命周期和探测状态
Kubernetes 探针支持的一个重要方面是它与应用程序生命周期的一致性。
AvailabilityState
(这是应用程序的内存中内部状态)之间存在显著差异
和实际的探针(公开该状态)。
根据应用程序生命周期的阶段,探测可能不可用。
Spring Boot 在启动和关闭期间发布应用程序事件,
探测器可以侦听此类事件并公开 AvailabilityState
信息。
下表显示了 HTTP 连接器在不同阶段的 AvailabilityState
和状态。
当 Spring Boot 应用程序启动时:
启动阶段 | LivenessState | 就绪状态 | HTTP 服务器 | 笔记 |
---|---|---|---|---|
开始 |
|
|
未启动 |
Kubernetes 会检查 “liveness” Probe,如果时间过长,则会重启应用程序。 |
开始 |
|
|
拒绝请求 |
应用程序上下文将刷新。应用程序执行启动任务,但尚未接收流量。 |
准备 |
|
|
接受请求 |
启动任务已完成。应用程序正在接收流量。 |
当 Spring Boot 应用程序关闭时:
关闭阶段 | 活动状态 | 就绪状态 | HTTP 服务器 | 笔记 |
---|---|---|---|---|
运行 |
|
|
接受请求 |
已请求关闭。 |
正常关闭 |
|
|
新请求被拒绝 |
如果启用,正常关闭将处理正在进行的请求。 |
关机完成 |
不适用 |
不适用 |
服务器已关闭 |
应用程序上下文已关闭,应用程序已关闭。 |
有关 Kubernetes 部署的更多信息,请参阅 Kubernetes 容器生命周期。 |
应用信息
应用程序信息公开了从 ApplicationContext
中定义的所有 InfoContributor
bean 收集的各种信息。
Spring Boot 包含许多自动配置的 InfoContributor
bean,您可以编写自己的 bean。
自动配置的 InfoContributors
在适当的时候, Spring 会自动配置以下InfoContributor
bean:
身份证 | 名字 | 描述 | 先决条件 |
---|---|---|---|
|
公开生成信息。 |
资源。 |
|
|
公开 |
没有。 |
|
|
公开 git 信息。 |
资源。 |
|
|
公开 Java 运行时信息。 |
没有。 |
|
|
公开 Operating System 信息。 |
没有。 |
|
|
公开进程信息。 |
没有。 |
是否启用单个贡献者由其属性控制。
不同的参与者对此属性具有不同的默认值,具体取决于其先决条件和他们公开的信息的性质。management.info.<id>.enabled
由于没有先决条件来指示应启用它们,因此 、 、 和 contributors 默认处于禁用状态。
可以通过将其属性设置为 来启用每个 。env
java
os
process
management.info.<id>.enabled
true
默认情况下,和 info 参与者处于启用状态。
可以通过将其属性设置为 来禁用 each。
或者,要禁用通常默认启用的每个参与者,请将该属性设置为 。build
git
management.info.<id>.enabled
false
management.info.defaults.enabled
false
自定义应用程序信息
启用贡献者后,您可以通过设置 Spring 属性来自定义端点公开的数据。
键下的所有 Environment
属性都会自动公开。
例如,您可以向文件添加以下设置:env
info
info.*
info
application.properties
-
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 提交信息
终端节点的另一个有用功能是,它能够在构建项目时发布有关源代码存储库状态的信息。
如果 GitProperties
Bean 可用,则可以使用终端节点公开这些属性。info
git
info
如果文件在 Classpath 的根目录中可用,则会自动配置 GitProperties bean。
有关更多详细信息,请参阅生成 Git 信息。git.properties |
默认情况下,终端节点公开 、 和 属性(如果存在)。
如果您不希望终端节点响应中出现这些属性中的任何一个,则需要将它们从文件中排除。
如果要显示完整的 git 信息(即 的完整内容),请使用该属性,如下所示:git.branch
git.commit.id
git.commit.time
git.properties
git.properties
management.info.git.mode
-
Properties
-
YAML
management.info.git.mode=full
management:
info:
git:
mode: "full"
要从端点完全禁用 git 提交信息,请将该属性设置为 ,如下所示:info
management.info.git.enabled
false
-
Properties
-
YAML
management.info.git.enabled=false
management:
info:
git:
enabled: false
构建信息
如果 BuildProperties
Bean 可用,则终端节点还可以发布有关您的构建的信息。
如果 Classpath 中有文件可用,则会发生这种情况。info
META-INF/build-info.properties
Maven 和 Gradle 插件都可以生成该文件。 有关更多详细信息,请参阅生成生成信息。 |
Java 信息
终端节点发布有关 Java 运行时环境的信息,有关更多详细信息,请参阅 JavaInfo
。info
OS 信息
终端节点发布有关您的操作系统的信息,有关更多详细信息,请参阅 OsInfo
。info
过程信息
终端节点发布有关您的进程的信息,请参阅 ProcessInfo
了解更多详细信息。info
编写自定义 InfoContributor
要提供自定义应用程序信息,您可以注册实现 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)
终端节点公开 Software Bill of Materials。
CycloneDX SBOM 可以自动检测,但其他格式也可以手动配置。sbom
然后,执行器端点将公开一个名为 “application” 的 SBOM,它描述了应用程序的内容。sbom
要在项目构建时自动生成CycloneDX SBOM,请参见Generate a CycloneDX SBOM部分。 |
其他 SBOM 格式
如果要以其他格式发布 SBOM,可以使用一些配置属性。
configuration 属性设置应用程序 SBOM 的位置。
例如,将此设置为 this 将使用 Classpath 上的资源内容。management.endpoint.sbom.application.location
classpath:sbom.json
/sbom.json
可自动检测 CycloneDX、SPDX 和 Syft 格式的 SBOM 的介质类型。
要覆盖自动检测到的媒体类型,请使用 configuration 属性 。management.endpoint.sbom.application.media-type
其他 SBOM
执行器终端节点可以处理多个 SBOM。
要添加 SBOMs,请使用 configuration property ,如以下示例所示:management.endpoint.sbom.additional
-
Properties
-
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: