Springboot Actuator监控

官网连接： Spring Boot Reference Documentation

13 Production-ready Features

Spring Boot包括许多附加功能，帮助您在将应用程序推向生产时监视和管理应用程序。您可以选择使用HTTP端点或JMX来管理和监视应用程序。 审计，健康和指标收集 也可以自动应用于应用程序。

13.1 使用 Enabling Production-ready Features

spring-boot-actuator模块提供所有Spring Boot的生产就绪功能。启用这些功能建议添加spring-boot-starter-actuator 依赖。

An actuator is a manufacturing term that refers to a mechanical device for moving or controlling something. Actuators can generate a large amount of motion from a small change.

actuator是生产期间为了改变或者监控设备。actuator可以以微小的改动产生巨大的改变。

要添加actuator到基于Maven的项目，请添加以下 Starter 依赖：

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

对于Gradle，使用以下声明：

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

13.2 端点 Endpoints

actuator端点允许您监视应用程序并与之交互。Spring Boot包含许多内置端点，允许您添加自己的端点。例如，健康端点提供基本的应用程序健康信息。

您可以启用或禁用每个端点，并通过HTTP或JMX暴露它们（使它们可以远程访问）。端点在启用和暴露时都视为可用。内置端点仅在可用时自动配置。大多数应用程序选择通过HTTP进行公开，其中端点的ID和前缀/actuator映射到URL。例如，默认情况下，health端点映射到/actuator/health

The following technology-agnostic endpoints are available:

如果你的应用是一个web应用(Spring MVC, Spring WebFlux, 或 Jersey），你还可以使用下面额外的端点：

13.2.1 开启端点

默认情况下，除shutdown端点外的所有端点都已启用。要配置启用端点，请使用其management.endpoint.<id>。以下示例启用shutdown(默认关闭)端点：

management.endpoint.shutdown.enabled=true

如果您希望选择性的开启端点，请设置 management.endpoints.enabled-by-default(默认开启) 属性为false，并使用单独的启用属性重新开启此端点。以下示例启用info端点并禁用其他所有端点：

management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true

Disabled endpoints are removed entirely from the application context. If you want to change only the technologies over which an endpoint is exposed, use the include and exclude properties instead.

禁用的端点将从应用程序上下文中完全删除。如果只想更改暴露端点，请改用include和exclude属性

13.2.2. 暴露端点

由于端点可能包含敏感信息，因此应仔细考虑何时公开它们。下表列出了默认暴露的内置端点：

要更改公开的端点，请使用以下特定的包含和排除属性：

include属性列出公开的端点的ID。exclude属性列出了不应公开的端点的ID。exclude属性优先于include属性。您可以使用include和exclude属性配置端点ID列表.

例如，要停止在JMX上公开所有端点，仅公开health和info端点，请使用以下属性：

management.endpoints.jmx.exposure.include=health,info

* can be used to select all endpoints. For example, to expose everything over HTTP except the env and beans endpoints, use the following properties:

*表示所有端点。例如，为了在HTTP上暴露所有端点，除了env和beans端点，可以使用下面配置：

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans

* has a special meaning in YAML, so be sure to add quotation marks if you want to include (or exclude) all endpoints.

*在YAML中具有特殊含义，因此如果要包含（或排除）所有端点，请务必添加引号。

If your application is exposed publicly, we strongly recommend that you also secure your endpoints.

如果您的应用程序公开，我们强烈建议您也保护端点。

If you want to implement your own strategy for when endpoints are exposed, you can register an EndpointFilter bean.

如果您想实现自己的端点公开策略，可以注册EndpointFilter bean。

13.2.3. Security

出于安全目的，默认情况下只有/health端点通过HTTP公开。您可以使用management.endpoints.web.export.include属性以配置公开的端点。

在设置 management.endpoints.web.exposure.include 之前。包括，确保暴露的 actuators 不包含敏感信息，通过将其放置在防火墙后进行保护，或通过类似于Spring Security的方式进行保护。

如果Spring Security位于类路径上，并且不存在其他WebSecurityConfigurerAdapter或SecurityFilterChain bean，则除/health之外的所有 actuators 都由Spring Boot自动配置保护。如果您自定义的WebSecurityConfigurerAdapter或SecurityFilterChain bean，Spring Boot自动配置将不会保护，并由你自己完全控制 actuators 访问规则。

如果您希望为HTTP端点配置自定义安全性（例如，仅允许具有特定角色的用户访问它们），Spring Boot提供了一些方便的RequestMatcher对象，可以与Spring security结合使用。

典型的Spring Security配置可如下示例：

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.requestMatcher(EndpointRequest.toAnyEndpoint());
        http.authorizeRequests((requests) -> requests.anyRequest().hasRole("ENDPOINT_ADMIN"));
        http.httpBasic(withDefaults());
        return http.build();
    }

}

The preceding example uses EndpointRequest.toAnyEndpoint() to match a request to any endpoint and then ensures that all have the ENDPOINT_ADMIN role. Several other matcher methods are also available on EndpointRequest. See the API documentation (HTML or PDF) for details.

前面的示例使用 EndpointRequest.toAnyEndpoint() 将请求匹配到任何端点，然后确保所有端点都具有ENDPOINT_ADMIN角色。EndpointRequest上还提供了其他几种匹配器方法。有关详细信息，请参阅API文档（HTML或PDF）。

If you deploy applications behind a firewall, you may prefer that all your actuator endpoints can be accessed without requiring authentication. You can do so by changing the management.endpoints.web.exposure.include property, as follows:

如果您在防火墙后面部署应用程序，您可能希望可以访问所有 actuator 端点而不需要身份验证。您可以通过更改management.endpoints.web.exposure.include来执行此操作，如下所示：

management.endpoints.web.exposure.include=*

此外，如果存在Spring Security，则需要添加自定义安全配置，以允许对端点进行未经身份验证的访问，如下例所示：

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.requestMatcher(EndpointRequest.toAnyEndpoint());
        http.authorizeRequests((requests) -> requests.anyRequest().permitAll());
        return http.build();
    }

}

在上述两个示例中，配置仅适用于 actuator 端点。由于 Spring Boot 的安全配置在任一个SecurityFilterChain bean的情况下完全失效，因此您需要在应用的其他部分中配置一个额外的SecurityFilterChain bean。

跨站点请求伪造保护 Cross Site Request Forgery Protection

由于Spring Boot依赖于Spring Security的默认值，因此CSRF保护默认打开。这意味着当使用默认安全配置时，POST（shutdown and loggers 端点）、PUT或DELETE的请求端点会收到403（禁止）错误。

We recommend disabling CSRF protection completely only if you are creating a service that is used by non-browser clients.

我们建议在创建非浏览器客户端使用的服务时完全禁用CSRF保护。

13.2.4. 配置端点 Configuring Endpoints

Endpoints automatically cache responses to read operations that do not take any parameters. To configure the amount of time for which an endpoint caches a response, use its cache.time-to-live property. The following example sets the time-to-live of the beans endpoint’s cache to 10 seconds:

端点对不带任何参数读取操作的响应会自动缓存。要配置端点响应缓存的时间，请使用 cache.time-to-live 这个属性。以下示例将bean端点缓存的生存时间设置为10秒：

management.endpoint.beans.cache.time-to-live=10s

The management.endpoint.<name> prefix uniquely identifies the endpoint that is being configured.

management.endpoint.<name> 前缀配置唯一标识端点。

13.2.5. web访问端点 Hypermedia for Actuator Web Endpoints

所有端点都有一个"discovery page"。默认情况下，"discovery page" 在/actuator 上是开启的。

要禁用"discovery page"，请将以下属性添加到应用程序属性中：

management.endpoints.web.discovery.enabled=false

配置自定义管理上下文路径后，"discovery page"将自动从/actuator移动到 管理上下文的根目录。例如，如果管理上下文路径为/management，则可以从/management获得"discovery page"。当管理上下文路径设置为/时，将禁用"discovery page"，以防止与其他映射发生冲突。

13.2.6. CORS Support

Cross-origin resource sharing （CORS）是W3C规范，允许您以灵活的方式允许哪种跨域请求。如果您使用SpringMVC或SpringWebFlux，则可以配置Actuator的web端点以支持此类场景。

CORS 在默认情况下是禁用的，只有在设置了management.endpoints.web.cors.allowed-origins属性才启用。以下配置允许从example.com 域名中通过GET和POST访问：

management.endpoints.web.cors.allowed-origins=https://example.com
management.endpoints.web.cors.allowed-methods=GET,POST

13.2.7 自定义端点 Implementing Custom Endpoints

如果添加@Endpoint注释的@Bean，任何用@ReadOperation、@WriteOperation或@DeleteOperation注释的方法都会自动通过JMX公开，在web应用程序中，也会通过HTTP公开。端点可以通过 Jersey、SpringMVC或SpringWebFlux以HTTP方式暴露出去。如果Jersey和SpringMVC都可用，则使用SpringMVC。

以下示例公开了一个返回自定义对象的读取操作：

您还可以使用@JmxEndpoint或@WebEndpoint编写特定的端点。这些端点仅限于各自的方式。例如，@WebEndpoint仅通过HTTP而不是JMX公开。

您可以使用@EndpointWebExtension和@EndpointJmxExtension编写特定于技术的扩展。这些注解允许您提供特定于技术的操作来扩充现有端点。

最后，如果您需要访问 web框架的功能，您可以实现servlet或Spring @Controller和@RestController 端点，代价是它们在JMX上不可用，或者在使用不同的web框架时不可用。

Receiving Input

端点上的操作通过其参数接收输入。当通过web公开时，这些参数的值取自URL的查询参数和JSON请求体。当通过JMX公开时，参数映射到MBean操作的参数。默认情况下需要参数。通过使用@javax.annotation.Nullable或 @org.springframework.lang.Nullable对它们进行注释，可以使参数为可选的。

您可以将JSON请求体中的每个根属性映射到端点的一个参数。考虑以下JSON请求体：

{
  "name": "test",
  "counter": 42
}

您可以使用它来调用一个写操作，该操作使用 String name 和 int counter 两个参数，如下例所示：

@WriteOperation
    public void updateData(String name, int counter) {
        // injects "test" and 42
    }

因为端点是技术不可知的，所以只能在方法签名中指定简单类型。特别是，不支持使用name 和 counter 属性的自定义类型声明单个参数。

为了让输入映射到操作方法的参数，实现端点的Java代码应该用-parameters编译，而Kotlin代码应该用-java-parameters。如果您使用Spring Boot的Gradle插件或使用Maven和spring-boot-starter-parent.，这些将自动生效。

Input Type Conversion

如果需要，传递给端点操作方法的参数会自动转换为所需的类型。在调用操作方法之前，通过JMX或HTTP接收的输入参数将通过使用ApplicationConversionService的实例以及使用@EndpointConverter限定的任何Converter或GenericConverter bean转换为所需类型。

Custom Web Endpoints

Jersey、Spring MVC 或Spring WebFlux使用@Endpoint、@WebEndpoint或@EndpointWebExtension通过HTTP方式将自动暴露。如果Jersey和SpringMVC都可用，则使用SpringMVC。

Web Endpoint Request Predicates

请求断言是 web公开端点上的每个操作自动生成的。

Path

The path of the predicate is determined by the ID of the endpoint and the base path of the web-exposed endpoints. The default base path is /actuator. For example, an endpoint with an ID of sessions uses /actuator/sessions as its path in the predicate.

访问路径由端点的ID和web公开端点的基本路径确定。默认基本路径为/actuator。例如，端点 ID为 sessions 使用/actuator/sessions作为其路径。

通过使用@Selector注解操作方法的一个或多个参数，可以进一步自定义路径。这样的参数作为路径变量添加到访问路径中。当调用端点操作时，变量的值将传递给操作方法。如果要捕获所有剩余的路径元素，可以在最后一个参数中添加@Selector(Match=ALL_REMAINING)，并使其成为与String[]转换兼容的类型。

HTTP method

访问的HTTP方法由操作类型决定，如下表所示：

Consumes

For a @WriteOperation (HTTP POST) that uses the request body, the consumes clause of the predicate is application/vnd.spring-boot.actuator.v2+json, application/json. For all other operations, the consumes clause is empty.

对于使用@WriteOperation（HTTP POST）请求体的请求，自定义条件是application/vnd.spring-boot.actuator.v2+json, application/json。对于所有其他操作，consumers子句为空。

Produces

The produces clause of the predicate can be determined by the produces attribute of the @DeleteOperation, @ReadOperation, and @WriteOperation annotations. The attribute is optional. If it is not used, the produces clause is determined automatically.

请求生产的条款可以由@DeleteOperation、@ReadOperation和@WriteOperation注解的products属性确定。该属性是可选的。如果不使用，将自动确定products子句。

If the operation method returns void or Void, the produces clause is empty. If the operation method returns a org.springframework.core.io.Resource, the produces clause is application/octet-stream. For all other operations, the produces clause is application/vnd.spring-boot.actuator.v2+json, application/json.

如果操作方法返回void或void，则products子句为空。如果操作方法返回org.springframework.core.io.Resource，products子句是application/octet-stream。对于所有其他操作，products子句是application/vnd.spring-boot.actuator.v2+json, application/json.。

Web Endpoint Response Status

端点操作的默认响应状态取决于操作类型（read, write, or delete）以及操作返回的内容（如果有）。

如果@ReadOperation返回一个值，则响应状态将为200（OK）。如果未返回值，则响应状态将为404（未找到）。

如果@WriteOperation或@DeleteOperation有返回值，则响应状态将为200（OK）。如果未返回值，则响应状态将为204（无内容）

如果在缺少必填参数的情况下调用操作，或者无法转换参数所需类型的调用，则不会调用操作方法，响应状态将为400（错误请求）。

Web Endpoint Range Requests

您可以使用HTTP范围请求请求部分HTTP资源。使用SpringMVC或SpringWebFlux时，返回org.springframework.core.io.Resource的操作自动支持范围请求。

使用Jersey时不支持范围请求。

Web Endpoint Security

web端点或特定于web的端点扩展上的操作可以接收当前java.security.Principal 或 org.springframework.boot.actuate.endpoint.SecurityContext作为方法参数。前者通常与@Nullable结合使用，为经过身份验证和未经身份验证的用户提供不同的行为。后者通常用于使用其isUserInRole（String）方法执行授权检查。

Servlet Endpoints

servlet可以通过实现一个用@ServletEndpoint注解的类作为端点公开，该类也实现了Supplier<EndpointServlet>.Servlet端点提供了与Servlet容器的深度集成，但牺牲了可移植性。它们旨在用于将现有servlet公开为端点。对于新端点，应尽可能首选@Endpoint和@WebEndpoint注解。

Controller Endpoints

You can use @ControllerEndpoint and @RestControllerEndpoint to implement an endpoint that is exposed only by Spring MVC or Spring WebFlux. Methods are mapped by using the standard annotations for Spring MVC and Spring WebFlux, such as @RequestMapping and @GetMapping, with the endpoint’s ID being used as a prefix for the path. Controller endpoints provide deeper integration with Spring’s web frameworks but at the expense of portability. The @Endpoint and @WebEndpoint annotations should be preferred whenever possible.

你可以使用@ControllerEndpoint和@RestControllerEndpoint来实现由SpringMVC或SpringWebFlux公开的端点。方法通过使用SpringMVC和SpringWebFlux的标准注解（如@RequestMapping和@GetMapping）进行映射，并将端点的ID用作路径的前缀。Controller endpoints提供了与Spring的web框架的深度集成，但牺牲了可移植性。应尽可能首选@Endpoint和@WebEndpoint注释。

13.2.8. 健康信息 Health Information

您可以使用health information来检查正在运行的应用程序的状态。当生产系统故障时，监控软件经常使用它来提醒某人。健康端点公开的信息取决于management.endpoint.health.show-details和 management.endpoint.health.show-components属性，可以使用以下值之一进行配置：

如果您已经保护了应用程序并希望始终使用，则安全配置必须允许经过身份验证和未经身份验证的用户访问健康端点。

健康信息是从HealthContributorRegistry的内容中收集的（默认情况下，ApplicationContext中定义的所有HealthContributor实例）。Spring Boot包含许多自动配置的HealthContributor，您也可以编写自己的。

HealthContributor可以是HealthIndicator或CompositeHealthContributer。HealthIndicator提供实际健康信息，包括状态。CompositeHealthContributor提供其他HealthContributors的组合。总之，贡献者形成了一个树结构来表示整个系统的健康状况

默认情况下，最终系统运行状况由StatusAggregator派生，它根据有序的状态列表对每个HealthIndicator的状态进行排序。排序列表中的第一个状态用作总体运行状况。如果没有HealthIndicator返回StatusAggregator已知的状态，则使用UNKNOWN状态。

You can use the HealthContributorRegistry to register and unregister health indicators at runtime.

您可以使用HealthContributorRegistry在运行时注册和注销健康指标。

Auto-configured HealthIndicators

如果合适，Spring Boot会自动配置下表中列出的HealthIndicators。您还可以通过配置management.health.key.enabled来启用或禁用所选指标。启用，键列在下表中：

到了这里，关于Springboot Actuator监控的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！