端点
Actuator 端点允许您监控应用程序并与之交互。Spring Boot 包括许多内置端点,并允许您添加自己的端点。例如,health
端点提供基本的应用程序运行状况信息。
您可以控制对每个单独端点的访问,并通过 HTTP 或 JMX 公开它们(使其可远程访问)。当允许访问端点并公开时,该端点被视为可用。内置端点仅在可用时才自动配置。大多数应用程序选择通过 HTTP 公开,其中端点的 ID 和前缀/actuator
映射到 URL。例如,默认情况下,health
endpoint 映射到/actuator/health
.
要了解有关执行器的端点及其请求和响应格式的更多信息,请参阅 API 文档。 |
以下与技术无关的终结点可用:
身份证 | 描述 |
---|---|
|
公开当前应用程序的审核事件信息。需要 |
|
显示应用程序中所有 Spring Bean 的完整列表。 |
|
公开可用缓存。 |
|
显示对配置类和自动配置类进行评估的条件,以及它们匹配或不匹配的原因。 |
|
显示所有 |
|
公开 Spring 的 |
|
显示已应用的任何 Flyway 数据库迁移。
需要一个或多个 |
|
显示应用程序运行状况信息。 |
|
显示 HTTP 交换信息(默认情况下,最近 100 个 HTTP 请求-响应交换)。
需要 |
|
显示任意应用程序信息。 |
|
显示 Spring Integration 图。
需要依赖于 |
|
显示和修改应用程序中记录器的配置。 |
|
显示已应用的任何 Liquibase 数据库迁移。
需要一个或多个 |
|
显示当前应用程序的“指标”信息,以诊断应用程序已记录的指标。 |
|
显示所有 |
|
显示有关 Quartz Scheduler 作业的信息。 需要消毒。 |
|
显示应用程序中的计划任务。 |
|
允许从 Spring Session 支持的会话存储中检索和删除用户会话。 需要使用 Spring Session 的基于 servlet 的 Web 应用程序。 |
|
允许正常关闭应用程序。 仅在使用罐装时有效。 默认禁用。 |
|
显示由 |
|
执行线程转储。 |
如果您的应用程序是 Web 应用程序(Spring MVC、Spring WebFlux 或 Jersey),则可以使用以下其他端点:
身份证 | 描述 |
---|---|
|
返回堆转储文件。
在 HotSpot JVM 上,一个 |
|
返回日志文件的内容(如果 |
|
以可由 Prometheus 服务器抓取的格式公开指标。
需要依赖于 |
控制对端点的访问
默认情况下,访问除shutdown
和heapdump
不受限制。
要配置对端点的允许访问,请使用其management.endpoint.<id>.access
财产。
以下示例允许不受限制地访问shutdown
端点:
-
Properties
-
YAML
management.endpoint.shutdown.access=unrestricted
management:
endpoint:
shutdown:
access: unrestricted
如果您希望访问是选择加入而不是选择退出,请将management.endpoints.access.default
属性设置为none
并使用单个端点access
属性以选择重新加入。
以下示例允许对loggers
端点并拒绝访问所有其他端点:
-
Properties
-
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
请求。
公开端点
默认情况下,只有运行状况终结点通过 HTTP 和 JMX 公开。 由于端点可能包含敏感信息,因此应仔细考虑何时公开它们。
若要更改要公开的终结点,请使用以下特定于技术的include
和exclude
性能:
属性 | 默认值 |
---|---|
|
|
|
|
|
|
|
|
这include
属性列出了公开的端点的 ID。 这exclude
属性列出了不应公开的端点的 ID。 这exclude
属性优先于include
财产。 您可以配置include
和exclude
属性,其中包含端点 ID 列表。
例如,要仅公开health
和info
endpoints over JMX,请使用以下属性:
-
Properties
-
YAML
management.endpoints.jmx.exposure.include=health,info
management:
endpoints:
jmx:
exposure:
include: "health,info"
*
可用于选择所有端点。例如,要通过 HTTP 公开除env
和beans
endpoints,请使用以下属性:
-
Properties
-
YAML
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans
management:
endpoints:
web:
exposure:
include: "*"
exclude: "env,beans"
* 在 YAML 中具有特殊含义,因此如果要包含(或排除)所有端点,请务必添加引号。 |
如果应用程序公开,强烈建议同时保护终结点。 |
如果要在端点公开时实现自己的策略,可以注册EndpointFilter 豆。 |
安全
出于安全考虑,只有/health
默认情况下,端点通过 HTTP 公开。
您可以使用management.endpoints.web.exposure.include
属性来配置公开的端点。
在设置management.endpoints.web.exposure.include ,确保公开的执行器不包含敏感信息,通过将它们放置在防火墙后面来保护,或者由 Spring Security 之类的东西保护。 |
如果 Spring Security 在类路径上并且没有其他SecurityFilterChain
bean 存在,除/health
由 Spring Boot 自动配置保护。
如果定义自定义SecurityFilterChain
bean,Spring Boot 自动配置会回退,让你完全控制执行器访问规则。
如果您希望为 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.toAnyEndpoint()
将请求与任何端点匹配,然后确保所有端点都有ENDPOINT_ADMIN
角色。
其他几种匹配器方法也可在EndpointRequest
.
有关详细信息,请参阅 API 文档。
如果将应用程序部署在防火墙后面,则可能希望无需身份验证即可访问所有执行器端点。
您可以通过更改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()
}
}
在上述两个示例中,配置仅适用于执行器端点。
由于 Spring Boot 的安全配置在存在任何SecurityFilterChain bean,您需要配置一个额外的SecurityFilterChain bean 具有适用于应用程序其余部分的规则。 |
跨站点请求伪造保护
由于 Spring Boot 依赖于 Spring Security 的默认值,因此默认情况下打开 CSRF 保护。
这意味着需要POST
(关闭和记录器端点),一个PUT
或DELETE
使用默认安全配置时,收到 403(禁止)错误。
我们建议仅在创建由非浏览器客户端使用的服务时完全禁用 CSRF 保护。 |
您可以在 Spring Security 参考指南中找到有关 CSRF 保护的其他信息。
配置端点
端点会自动缓存对不采用任何参数的读取作的响应。
要配置端点缓存响应的时间量,请使用其cache.time-to-live
财产。
以下示例设置beans
端点的缓存到 10 秒:
-
Properties
-
YAML
management.endpoint.beans.cache.time-to-live=10s
management:
endpoint:
beans:
cache:
time-to-live: "10s"
这management.endpoint.<name> prefix 唯一标识正在配置的终结点。 |
清理敏感值
返回的信息/env
,/configprops
和/quartz
端点可能是敏感的,因此默认情况下,值始终完全清理(替换为 )。******
只有在以下情况下,才能以未经清理的形式查看值:
-
这
show-values
属性已设置为never
-
无自定义
SanitizingFunction
Beans应用
这show-values
可以为可清理的端点配置为以下值之一:
-
never
- 值始终完全清理(替换为******
) -
always
- 向所有用户显示值(只要没有SanitizingFunction
bean 适用) -
when-authorized
- 值仅向授权用户显示(只要没有SanitizingFunction
bean 适用)
对于 HTTP 端点,如果用户已进行身份验证并具有由端点的 roles 属性配置的角色,则该用户被视为已授权。默认情况下,任何经过身份验证的用户都是授权的。
对于 JMX 端点,所有用户始终获得授权。
以下示例允许所有使用admin
role 从/env
端点。未经授权的用户,或没有admin
role,将仅看到经过清理的值。
-
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 已被定义。 |
用于执行器 Web 端点的超介质
将添加一个“发现页面”,其中包含指向所有端点的链接。
“发现页面”可在/actuator
默认情况下。
若要禁用“发现页”,请将以下属性添加到应用程序属性:
-
Properties
-
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
财产。
以下配置允许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 获取完整的选项列表。 |
实现自定义端点
如果您添加@Bean
注释为@Endpoint
,任何用@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作的参数。
默认情况下,参数是必需的。
可以通过使用以下任一注释来使它们成为可选的@javax.annotation.Nullable
或@Nullable
.
您可以将 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
以及任何Converter
或GenericConverter
符合条件的豆子@EndpointConverter
.
自定义 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
(HTTPPOST
)使用请求正文的consumes
谓词的子句是application/vnd.spring-boot.actuator.v2+json, application/json
.
对于所有其他作,consumes
子句为空。
生产
这produces
谓词的子句可以由produces
属性的@DeleteOperation
,@ReadOperation
和@WriteOperation
附注。
该属性是可选的。
如果不使用它,则produces
子句是自动确定的。
Web 端点响应状态
终结点作的默认响应状态取决于作类型(读取、写入或删除)以及作返回的内容(如果有)。
如果@ReadOperation
返回一个值,响应状态将为 200 (OK)。
如果它不返回值,则响应状态将为 404(未找到)。
如果@WriteOperation
或@DeleteOperation
返回一个值,响应状态将为 200 (OK)。
如果它不返回值,则响应状态将为 204(无内容)。
如果调用作时没有必需参数或参数无法转换为所需类型,则不会调用作方法,响应状态将为 400(错误请求)。
Web 端点范围请求
您可以使用 HTTP 范围请求来请求部分 HTTP 资源。
使用 Spring MVC 或 Spring Web Flux 时,返回Resource
自动支持范围请求。
使用 Jersey 时不支持范围请求。 |
Web 端点安全
对 Web 端点或特定于 Web 的端点扩展的作可以接收当前Principal
或SecurityContext
作为方法参数。
前者通常与以下任一结合使用@javax.annotation.Nullable
或@Nullable
为经过身份验证和未经身份验证的用户提供不同的行为。
后者通常用于通过使用其isUserInRole(String)
方法。
健康信息
您可以使用运行状况信息来检查正在运行的应用程序的状态。
监控软件通常使用它来在生产系统出现故障时向某人发出警报。
由health
endpoint 依赖于management.endpoint.health.show-details
和management.endpoint.health.show-components
属性,可以使用以下值之一进行配置:
名称 | 描述 |
---|---|
|
从不显示详细信息。 |
|
详细信息仅向授权用户显示。
授权角色可以通过以下方式配置 |
|
详细信息将显示给所有用户。 |
默认值为never
.
当用户处于一个或多个端点角色时,该用户被视为已获得授权。
如果终结点未配置角色(默认),则所有经过身份验证的用户都被视为已授权。
您可以使用management.endpoint.health.roles
财产。
如果您已保护您的应用程序并希望使用always ,则安全配置必须允许经过身份验证和未经身份验证的用户访问运行状况终结点。 |
健康信息是从HealthContributorRegistry
(默认情况下,所有HealthContributor
在ApplicationContext
).
Spring Boot 包括许多自动配置的HealthContributor
bean,你也可以自己写。
一个HealthContributor
可以是HealthIndicator
或CompositeHealthContributor
.
一个HealthIndicator
提供实际的健康信息,包括Status
.
一个CompositeHealthContributor
提供其他HealthContributor
实例。
总之,参与者形成一个树结构来表示整个系统运行状况。
默认情况下,最终系统运行状况由StatusAggregator
,它对每个HealthIndicator
基于状态的有序列表。
排序列表中的第一个状态用作总体运行状况。
如果没有HealthIndicator
返回已知的状态StatusAggregator
一UNKNOWN
状态。
您可以使用HealthContributorRegistry 在运行时注册和注销运行状况指标。 |
自动配置的运行状况指标
在适当的时候,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 将向您发出警告,但它仍将返回 HTTP 200 以免中断应用程序。您可以使用此阈值为自己提供足够的准备时间来轮换即将过期的证书。 |
附加HealthIndicator
bean 可用,但默认情况下未启用:
钥匙 | 名称 | 描述 |
---|---|---|
|
公开“活动”应用程序可用性状态。 |
|
|
公开“就绪”应用程序可用性状态。 |
编写自定义 HealthIndicators
要提供自定义运行状况信息,您可以注册实现HealthIndicator
接口。
您需要提供health()
方法并返回一个Health
响应。
这Health
响应应包括状态,并且可以选择包含要显示的其他详细信息。
以下代码显示了一个示例HealthIndicator
实现:
-
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 是 bean 的名称,不带HealthIndicator 后缀,如果存在。
在前面的示例中,运行状况信息在名为my . |
运行状况指示器通常通过 HTTP 调用,需要在任何连接超时之前做出响应。
Spring Boot 将记录任何响应时间超过 10 秒的运行状况指示器的警告消息。
如果要配置此阈值,可以使用management.endpoint.health.logging.slow-indicator-threshold 财产。 |
除了 Spring Boot 的预定义Status
类型Health
可以返回自定义Status
这代表一种新的系统状态。
在这种情况下,您还需要提供StatusAggregator
接口,或者您必须使用management.endpoint.health.status.order
configuration 属性。
例如,假设新的Status
代码为FATAL
正在您的一个HealthIndicator
实现。
要配置严重性顺序,请将以下属性添加到应用程序属性:
-
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 状态代码反映了整体运行状况。
默认情况下,OUT_OF_SERVICE
和DOWN
映射到 503。
任何未映射的运行状况,包括UP
,映射到 200。
如果通过 HTTP 访问运行状况终结点,您可能还需要注册自定义状态映射。
配置自定义映射会禁用DOWN
和OUT_OF_SERVICE
.
如果要保留默认映射,则必须显式配置它们以及任何自定义映射。
例如,以下属性映射FATAL
设置为 503(服务不可用),并保留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 豆。 |
下表显示了内置状态的默认状态映射:
地位 | 映射 |
---|---|
|
|
|
|
|
默认情况下没有映射,因此 HTTP 状态为 |
|
默认情况下没有映射,因此 HTTP 状态为 |
反应性健康指标
对于响应式应用程序,例如那些使用 Spring WebFlux 的应用程序,ReactiveHealthContributor
提供用于获取应用程序运行状况的非阻塞协定。
类似于传统的HealthContributor
,健康信息是从ReactiveHealthContributorRegistry
(默认情况下,所有HealthContributor
和ReactiveHealthContributor
在ApplicationContext
).
定期HealthContributor
不检查响应式 API 的实例将在弹性调度程序上执行。
在响应式应用程序中,您应该使用ReactiveHealthContributorRegistry 在运行时注册和注销运行状况指标。
如果您需要注册常规HealthContributor ,你应该用ReactiveHealthContributor#adapt . |
要从响应式 API 提供自定义运行状况信息,您可以注册实现ReactiveHealthIndicator
接口。
以下代码显示了一个示例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
豆:
钥匙 | 名称 | 描述 |
---|---|---|
|
检查 Cassandra 数据库是否已启动。 |
|
|
检查 Couchbase 集群是否已启动。 |
|
|
检查 Elasticsearch 集群是否已启动。 |
|
|
检查 Mongo 数据库是否已启动。 |
|
|
检查 Neo4j 数据库是否已启动。 |
|
|
检查 Redis 服务器是否已启动。 |
如有必要,反应指示器取代常规指示器。
此外,任何HealthIndicator 未显式处理的自动包装。 |
健康组
有时将健康指标组织成可用于不同目的的组很有用。
要创建运行状况指示器组,您可以使用management.endpoint.health.group.<name>
属性,并指定运行状况指示器 ID 列表,以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
设置作为系统运行状况。
但是,您也可以按组定义这些值。
您还可以覆盖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
您可以使用@Qualifier("groupname") 如果您需要注册自定义StatusAggregator 或HttpCodeStatusMapper 用于组的豆子。 |
运行状况组还可以包含/排除CompositeHealthContributor
.
您还可以仅包含/排除CompositeHealthContributor
.
这可以使用组件的完全限定名称来完成,如下所示:
management.endpoint.health.group.custom.include="test/primary"
management.endpoint.health.group.custom.exclude="test/primary/b"
在上面的示例中,custom
组将包括HealthContributor
与名称primary
它是复合材料的一个组成部分test
.
这里primary
本身是一个复合,而HealthContributor
与名称b
将被排除在custom
群。
可以在主端口或管理端口上的附加路径上提供运行状况组。 这在 Kubernetes 等云环境中非常有用,在云环境中,出于安全目的,为执行器端点使用单独的管理端口是很常见的。 使用单独的端口可能会导致运行状况检查不可靠,因为即使运行状况检查成功,主应用程序也可能无法正常工作。 可以配置运行状况组的其他路径,如下所示:
management.endpoint.health.group.live.additional-path="server:/healthz"
这将使live
运行状况组在主服务器端口上可用,位于/healthz
.
前缀是强制性的,必须是server:
(代表主服务器端口)或management:
(表示管理端口(如果已配置)。
路径必须是单个路径段。
数据源运行状况
这DataSource
运行状况指示器显示标准数据源和路由数据源 Bean 的运行状况。
路由数据源的运行状况包括其每个目标数据源的运行状况。
在运行状况终结点的响应中,每个路由数据源的目标都使用其路由键命名。
如果您不想在指标的输出中包含路由数据源,请将management.health.db.ignore-routing-data-sources
自true
.
Kubernetes 探针
部署在 Kubernetes 上的应用程序可以使用容器探针提供有关其内部状态的信息。 根据您的 Kubernetes 配置,kubelet 会调用这些探针并对结果做出反应。
默认情况下,Spring Boot 管理应用程序可用性状态。
如果部署在 Kubernetes 环境中,执行器会从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> 应设置为执行器端点可用的端口。
它可以是主 Web 服务器端口,也可以是单独的管理端口,如果"management.server.port" 属性已设置。 |
仅当应用程序在 Kubernetes 环境中运行时,才会自动启用这些运行状况组。
您可以使用management.endpoint.health.probes.enabled
configuration 属性。
如果应用程序启动时间超过配置的活跃期,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 探针检查外部状态
执行器将“活动”和“就绪”探测配置为运行状况组。 这意味着所有运行状况组功能都可供他们使用。 例如,您可以配置其他运行状况指示器:
-
Properties
-
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 不接受任何传入连接。
没有 HTTP 错误响应(503 等),因为没有连接。
一项服务type=LoadBalancer 可能接受也可能不接受连接,具体取决于提供商。
具有显式入口的服务也会以依赖于实现的方式进行响应——入口服务本身必须决定如何处理来自下游的“拒绝连接”。
HTTP 503 很可能在负载均衡器和入口的情况下出现。 |
此外,如果应用程序使用 Kubernetes 自动缩放,则它可能会对从负载均衡器中取出的应用程序做出不同的反应,具体取决于其自动缩放器配置。
应用程序生命周期和探测状态
Kubernetes 探针支持的一个重要方面是它与应用程序生命周期的一致性。
之间存在显着差异AvailabilityState
(即应用程序的内存内部状态)
以及实际的探针(暴露了该状态)。
根据应用程序生命周期的阶段,探测可能不可用。
Spring Boot 在启动和关闭期间发布应用程序事件,
探测器可以监听此类事件并公开AvailabilityState
信息。
下表显示了AvailabilityState
以及不同阶段的 HTTP 连接器状态。
当 Spring Boot 应用程序启动时:
启动阶段 | LivenessState | 就绪状态 | HTTP 服务器 | 笔记 |
---|---|---|---|---|
开始 |
|
|
未开始 |
Kubernetes 会检查“活动性”探针,如果时间过长,则重新启动应用程序。 |
开始 |
|
|
拒绝请求 |
应用程序上下文将刷新。应用程序执行启动任务,但尚未接收流量。 |
准备 |
|
|
接受请求 |
启动任务已完成。应用程序正在接收流量。 |
当 Spring Boot 应用程序关闭时:
关机阶段 | 活跃状态 | 就绪状态 | HTTP 服务器 | 笔记 |
---|---|---|---|---|
运行 |
|
|
接受请求 |
已请求关闭。 |
正常关机 |
|
|
新请求被拒绝 |
如果启用,则正常关闭会处理正在进行的请求。 |
关机完成 |
不适用 |
不适用 |
服务器已关闭 |
应用程序上下文已关闭,应用程序已关闭。 |
有关 Kubernetes 部署的更多信息,请参阅 Kubernetes 容器生命周期。 |
申请信息
应用程序信息公开从所有InfoContributor
bean 在ApplicationContext
.
Spring Boot 包括许多自动配置的InfoContributor
bean,你可以自己写。
自动配置的信息贡献者
在适当的情况下,Spring 会自动配置以下内容InfoContributor
豆:
身份证 | 名称 | 描述 | 前提条件 |
---|---|---|---|
|
公开生成信息。 |
一个 |
|
|
从 |
没有。 |
|
|
公开 git 信息。 |
一个 |
|
|
公开 Java 运行时信息。 |
没有。 |
|
|
公开作系统信息。 |
没有。 |
|
|
公开进程信息。 |
没有。 |
|
|
公开 SSL 证书信息。 |
配置了 SSL 捆绑包。 |
是否启用单个贡献者由其控制management.info.<id>.enabled
财产。
不同的参与者对此属性有不同的默认值,具体取决于其前提条件和他们公开的信息的性质。
由于没有前提条件来指示应启用它们,因此env
,java
,os
和process
默认情况下,参与者处于禁用状态。这ssl
contributor 的前提条件是配置了 SSL Bundle,但默认情况下它是禁用的。
每个都可以通过设置其management.info.<id>.enabled
属性设置为true
.
这build
和git
信息参与者默认启用。
每个都可以通过设置其management.info.<id>.enabled
属性设置为false
.
或者,要禁用通常默认启用的每个贡献者,请将management.info.defaults.enabled
属性设置为false
.
自定义应用程序信息
当env
contributor 启用后,您可以自定义info
endpoint 通过设置info.*
弹簧属性。
都Environment
属性下的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"
除了对这些值进行硬编码,您还可以在构建时扩展信息属性。 假设您使用 Maven,您可以重写前面的示例,如下所示:
|
Git 提交信息
另一个有用的功能info
endpoint 是它发布有关您的状态的信息的能力git
生成项目时的源代码存储库。
如果GitProperties
bean 可用,您可以使用info
endpoint 来公开这些属性。
一个GitProperties 如果git.properties 文件位于类路径的根目录中。
有关更多详细信息,请参阅生成 Git 信息。 |
默认情况下,终结点会公开git.branch
,git.commit.id
和git.commit.time
属性(如果存在)。
如果您不希望在端点响应中包含任何这些属性,则需要将它们从git.properties
文件。
如果要显示完整的 git 信息(即git.properties
),使用management.info.git.mode
属性,如下所示:
-
Properties
-
YAML
management.info.git.mode=full
management:
info:
git:
mode: "full"
要从info
endpoint 完全,请将management.info.git.enabled
属性设置为false
如下:
-
Properties
-
YAML
management.info.git.enabled=false
management:
info:
git:
enabled: false
构建信息
如果BuildProperties
bean 可用,则info
endpoint 还可以发布有关您的构建的信息。
如果META-INF/build-info.properties
文件在类路径中可用。
Maven 和 Gradle 插件都可以生成该文件。 有关更多详细信息,请参阅生成构建信息。 |
Java 信息
这info
endpoint 发布有关 Java 运行时环境的信息,请参阅JavaInfo
了解更多详情。
作系统信息
这info
endpoint 发布有关您的作系统的信息,请参阅OsInfo
了解更多详情。
工艺信息
这info
endpoint 发布有关您的流程的信息,请参阅ProcessInfo
了解更多详情。
SSL 信息
这info
endpoint 发布有关 SSL 证书(通过 SSL 捆绑包配置)的信息,请参阅SslInfo
了解更多详情。此终结点重用SslHealthIndicator
:如果 SSL 证书在此阈值定义的时间跨度内无效,则会触发警告。请参阅management.health.ssl.certificate-validity-warning-threshold
财产。
编写自定义 InfoContributors
要提供自定义应用程序信息,您可以注册实现InfoContributor
接口。
以下示例贡献了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
endpoint,您应该会看到包含以下附加条目的响应:
{
"example": {
"key" : "value"
}
}
软件物料清单 (SBOM)
这sbom
endpoint 公开软件物料清单。
CycloneDX SBOM 可以自动检测,但也可以手动配置其他格式。
这sbom
然后,执行器端点将公开一个名为“应用程序”的 SBOM,它描述了应用程序的内容。
要在项目构建时自动生成 CycloneDX SBOM,请参阅生成 CycloneDX SBOM 部分。 |
其他 SBOM 格式
如果要以不同的格式发布 SBOM,可以使用一些配置属性。
配置属性management.endpoint.sbom.application.location
设置应用程序 SBOM 的位置。
例如,将此设置为classpath:sbom.json
将使用/sbom.json
类路径上的资源。
自动检测 CycloneDX、SPDX 和 Syft 格式的 SBOM 的介质类型。
若要覆盖自动检测到的媒体类型,请使用 configuration 属性management.endpoint.sbom.application.media-type
.
其他 SBOM
执行器端点可以处理多个 SBOM。
要添加 SBOM,请使用 configuration 属性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:
前缀可用于防止文件不存在时启动失败。