Spring Boot 2.0官方文档之 Actuator

前言:本文翻译自Spring Boot 2.0.1.RELEASE官方文档,该Spring Boot版本是当前(2018年4月份)官方推荐版本,因Spring Boot 2.0的Actuator与之前版本有较大不同,而网上相关博文资料较旧,故建议阅读官方文档再做实践.转载需经本人同意,注明出处方可转载.

执行器（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.

1. 开启Actuator

spring-boot-actuator模块提供Spring Boot所有的production-ready特性，启用该特性的最简单方式是添加spring-boot-starter-actuator ‘Starter’依赖。
按以下配置为Maven项目添加执行器：

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

对于Gradle，使用下面的声明：

dependencies {
    compile("org.springframework.boot:spring-boot-starter-actuator")
}

2. 端点(Endpoints)

执行器端点（endpoints）可用于监控应用及与应用进行交互，Spring Boot包含很多内置的端点，你也可以添加自己的。例如，health端点提供了应用的基本健康信息。
每个端点都可以启用或禁用。这控制着端点是否被创建，并且它的bean是否存在于应用程序上下文中。要远程访问端点，还必须通过JMX或HTTP进行暴露,大部分应用选择HTTP，端点的ID映射到一个带/actuator前缀的URL。例如，health端点默认映射到/actuator/health。

注意:
Spring Boot 2.0的端点基础路径由“/”调整到”/actuator”下,如：/info调整为/actuator/info
可以通过以下配置改为和旧版本一致:

management.endpoints.web.base-path=/

下面的端点都是可用的：

如果使用web应用(Spring MVC, Spring WebFlux, 或者 Jersey)，你还可以使用以下端点：

注意
Spring Boot 2.0的端点和之前的版本有较大不同,使用时需注意
另外,端点的监控机制也有很大不同,启用了不代表可以直接访问,还需要将其暴露出来,传统的management.security管理已被标记为不推荐,现在一般使用单独启用并暴露

2.1 启用端点

默认情况下，除shutdown以外的所有端点均已启用。要配置单个端点的启用，请使用management.endpoint.<id>.enabled属性。以下示例启用shutdown端点：

management.endpoint.shutdown.enabled=true

另外可以通过management.endpoints.enabled-by-default来修改全局端口默认配置,以下示例启用info端点并禁用所有其他端点：

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

注意
禁用的端点将从应用程序上下文中完全删除。如果您只想更改端点公开(对外暴露)的技术，请改为使用include和exclude属性,详情见下文

2.2 暴露端点

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

要更改公开哪些端点，请使用以下技术特定的include和exclude属性：

include属性列出了公开的端点的ID,exclude属性列出了不应该公开的端点的ID
exclude属性优先于include属性。包含和排除属性都可以使用端点ID列表进行配置。

注意
这里的优先级是指同一端点ID,同时出现在include属性表和exclude属性表里,exclude属性优先于include属性,即此端点没有暴露

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

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

*可以用来选择所有端点。例如，要通过HTTP公开除env和beans端点之外的所有内容，请使用以下属性：

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

注意
*在YAML中有特殊的含义，所以如果你想包含（或排除）所有的端点，一定要加引号，如下例所示：

如果您的应用程序对外公开，我们强烈建议您保护您的端点,方法见下文。
如果您希望在暴露端点时实施您自己的策略，您可以注册一个EndpointFilter bean。

management:
  endpoints:
    web:
      exposure:
        include: '*'

2.3 保护HTTP端点

您应该注意保护HTTP端点的方式与使用其他任何敏感网址的方式相同。如果存在Spring Security，则默认使用Spring Security的内容协商策略(content-negotiation strategy)保护端点。例如，如果您希望为HTTP端点配置自定义安全性，比方说只允许具有特定角色的用户访问它们,Spring Boot提供了一些方便的RequestMatcher对象，可以与Spring Security结合使用。
一个典型的Spring Security配置可能看起来像下面的例子：

@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
                .anyRequest().hasRole("ENDPOINT_ADMIN")
                .and()
            .httpBasic();
    }
}

上例使用EndpointRequest.toAnyEndpoint（）将请求与所有端点进行匹配，然后确保所有端点都具有ENDPOINT_ADMIN角色。有关详细信息，请参阅API文档（HTML或PDF）。

如果您的应用程序部署在防火墙后面，您可能更喜欢所有的执行器端点都可以在无需验证的情况下进行访问。

您可以通过更改management.endpoints.web.exposure.include属性来完成此操作，如下所示：

management.endpoints.web.exposure.include=*

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

@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
            .anyRequest().permitAll()
    }
}

2.4 配置端点缓存时间

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

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

注意
在进行经过验证的HTTP请求时，Principal将被视为端点的输入，因此不会缓存响应。

2.5 端点的发现页

“discovery page”添加了指向所有端点的链接。默认情况下，“discovery page”可通过/actuator访问。
需要注意的是,这里的/actuator指的是端点的基础路径,如果基础路径改变,发现页访问路径会跟着改变.
例如，如果基础路径是/manage，则发现页面可从/ manage获得
但是,当基础路径设置为/时，禁用发现页面以防止与其他映射发生冲突的可能性。
基础路径的设置见下

2.6 端点的路径

默认情况下，端点通过使用端点的ID在/actuator路径下的HTTP上公开。例如，beans端点暴露在/actuator/beans下。如果要将端点映射到其他路径，则可以使用management.endpoints.web.path-mapping属性。另外，如果您想更改基本路径，则可以使用management.endpoints.web.base-path。
以下示例将/actuator/health重新映射到/healthcheck：

management.endpoints.web.base-path=/
management.endpoints.web.path-mapping.health=healthcheck

2.7 跨域支持

跨源资源共享（Cross-origin resource sharing,CORS）是W3C规范，允许您以灵活的方式指定授权哪种跨域请求。如果您使用Spring MVC或Spring WebFlux，则可以配置Actuator的Web端点来支持这些场景。

默认情况下，CORS支持处于禁用状态，只有在设置了management.endpoints.web.cors.allowed-origins属性后才能启用。以下配置允许来自example.com域的GET和POST调用：

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

请参阅CorsEndpointProperties以获取完整的选项列表。

2.8 实现自定义端点

如果添加用@Endpoint注解的@Bean，则任何使用@ReadOperation，@WriteOperation或@DeleteOperation注释的方法都会自动通过JMX公开，并且也可以通过HTTP在Web应用程序中通过HTTP公开。也可以使用Jersey，Spring MVC或Spring WebFlux通过HTTP公开端点。

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

您可以使用@EndpointWebExtension和@EndpointJmxExtension编写技术特定的扩展。这些注释可让您提供技术特定的操作，以增强现有端点。

最后，如果您需要访问特定于Web框架的功能，则可以实现Servlet或Spring @Controller和@RestController端点，但代价是它们不能通过JMX或使用其他Web框架提供。

2.8.1 接收输入

端点上的操作通过参数接收输入。
当通过网络公开时，这些参数的值取自URL的查询参数和JSON请求主体。
通过JMX公开时，参数将映射到MBean操作的参数。
参数默认是必需的,可以通过使用@org.springframework.lang.Nullable注释使其成为可选的。

为了允许输入映射到操作方法的参数，实现端点的Java代码应该用-parameters编译，实现端点的Kotlin代码应该用 -java-parameters编译。
如果您使用的是Spring Boot的Gradle插件，或者您正在使用Maven和spring-boot-starter-parent，则会自动发生。

输入类型转换
传递给端点操作方法的参数在必要时会自动转换为所需的类型。在调用操作方法之前，使用ApplicationConversionService的实例将通过JMX或HTTP请求接收到的输入转换为所需的类型。

2.8.2 自定义Web端点

对使用Jersey，Spring MVC或Spring WebFlux的@Endpoint，@WebEndpoint或@WebEndpointExtension操作通过HTTP自动公开。

• Web端点请求谓词
  一个请求谓词会自动为web暴露端点上的每个操作生成。
• 路径
  谓词的路径由端点的ID和Web暴露端点的基本路径决定。默认的基本路径是/actuator。例如，具有IDsessions的端点将使用/ actuator / sessions作为谓词中的路径。
  可以通过使用@Selector注释操作方法的一个或多个参数来进一步定制路径。这样的参数作为路径变量添加到路径谓词中。当调用端点操作时，该变量的值被传递给操作方法。
• HTTP方法
  谓词的HTTP方法由操作类型决定，如下表所示：

• 消费
  • 对于使用请求体的@WriteOperation（POST），谓词的consumes子句是application/vnd.spring-boot.actuator.v2+json, application/json。
  • 对于所有其他操作，消费条款是空的。
• 生产
  谓词的生产条款可以通过@DeleteOperation，@ReadOperation和@WriteOperation注释的produce属性来确定。该属性是可选的。如果未使用，则自动确定生产条款。
  • 如果操作方法返回void或Void，则produce子句为空。如果操作方法返回一个org.springframework.core.io.Resource，则生产条款是application/octet-stream。
  • 对于所有其他操作，生产条款是application/vnd.spring-boot.actuator.v2+json, application/json。
• Web端点响应状态

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

• @ReadOperation返回一个值，响应状态将为200（OK）。如果它没有返回值，则响应状态将为404（未找到）。
• 如果@WriteOperation或@DeleteOperation返回一个值，则响应状态将为200（OK）。如果它没有返回值，则响应状态将为204（无内容）。
• 如果调用时缺少必需参数，或者使用无法转换为所需类型的参数，则不会调用操作方法，响应状态将为400（错误请求）。
  • Web端点范围请求
    HTTP范围请求可用于请求部分HTTP资源。在使用Spring MVC或Spring Web Flux时，返回org.springframework.core.io.Resource的操作会自动支持范围请求。使用Jersey时不支持范围请求。
  • Web端点安全
    对Web端点或基于Web的端点扩展的操作可以接收当前的java.security.Principal或org.springframework.boot.actuate.endpoint.SecurityContext作为方法参数。前者通常与@Nullable结合使用，为经过身份验证的用户和未经身份验证的用户提供不同的行为。后者通常用于使用isUserInRole（String）方法执行授权检查。

2.8.3 Servlet端点

通过实现一个用@ServletEndpoint注解的类来实现Supplier<EndpointServlet>，Servlet可以作为端点公开。Servlet端点提供了与Servlet容器的更深层次的集成，但是具有可移植性。它们旨在用于将现有的Servlet作为端点公开。对于新的端点，只要有可能，应该首选@Endpoint和@WebEndpoint注释。

2.8.4 控制器端点

@ControllerEndpoint和@RestControllerEndpoint可用于实现仅由Spring MVC或Spring WebFlux公开的端点。使用标准注释Spring MVC和Spring WebFlux注释（如@RequestMapping和@GetMapping）来映射方法，并将端点ID用作路径的前缀。控制器端点提供了与Spring的Web框架的更深层次的集成，但代价是可移植性。只要有可能，应该首选@Endpoint和@WebEndpoint注释。

2.9 健康信息

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

默认值为never。
当用户处于一个或多个端点角色时，它被认为是被授权的。
如果端点没有配置角色（默认），则认为所有经过身份验证的用户均被授权。可以使用management.endpoint.health.roles属性配置角色。

2.9.1 自动配置的HealthIndicators

在适当情况下，以下HealthIndicators可由Spring Boot自动配置：

您可以通过设置management.health.defaults.enabled属性来禁用它们。

2.9.2 编写自定义HealthIndicators

要提供自定义健康信息，您可以注册实现HealthIndicator接口的Spring bean。您需要提供health（）方法的实现并返回Health响应。Health响应应包含一个状态，并可以选择包含要显示的其他详细信息。以下代码显示了一个示例HealthIndicator实现：

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(); // perform some specific health check
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }
}

给定HealthIndicator的标识符是没有HealthIndicator后缀的bean的名称（如果存在）。在前面的示例中，健康信息在名为my的条目中可用。

例如,在上面的实例中,如果check()返回的结果是500,则health端点的信息为

{
    "status": "DOWN",
    "details": {
        "my": {
            "status": "DOWN",
            "details": {
                "Error Code": 500
            }
        }
    }
}

注意:要先设置management.endpoint.health.show-details属性使其可见.

除了Spring Boot的预定义状态类型外，Health还可以返回代表新系统状态的自定义状态。在这种情况下，还需要提供HealthAggregator接口的自定义实现，或者必须使用management.health.status.order配置属性来配置默认实现。

例如，假定您的一个HealthIndicator实例中正在使用代码为FATAL的新状态。要配置重要性顺序，请将以下属性添加到应用程序属性中：

management.health.status.order=FATAL, DOWN, OUT_OF_SERVICE, UNKNOWN, UP

响应中的HTTP状态代码反映整体健康状况（例如，UP映射为200，而OUT_OF_SERVICE和DOWN映射为503）。如果您通过HTTP访问健康端点，则可能还需要注册自定义状态映射。例如，以下属性将FATAL映射为503（服务不可用）：

management.health.status.http-mapping.FATAL=503

如果你需要更多的控制，你可以定义你自己的HealthStatusHttpMapper bean。

下表显示了内置状态的默认状态映射：

2.9.3 反应性健康指标

对于反应式应用程序（例如使用Spring WebFlux的应用程序），ReactiveHealthIndicator提供了获取应用程序运行状况的非阻塞合同。与传统的HealthIndicator类似，健康信息从ApplicationContext中定义的所有ReactiveHealthIndicatorbean中收集。在弹性调度器上包含并执行不检查反应性API的常规HealthIndicator bean。

为了从反应式API提供定制的健康信息，您可以注册实现ReactiveHealthIndicator接口的Spring bean。以下代码显示了一个示例ReactiveHealthIndicator实现：

@Component
public class MyReactiveHealthIndicator implements ReactiveHealthIndicator {
    @Override
    public Mono<Health> health() {
        return doHealthCheck() //perform some specific health check that returns a Mono<Health>
            .onErrorResume(ex -> Mono.just(new Health.Builder().down(ex).build())));
    }
}

要自动处理错误，请考虑从AbstractReactiveHealthIndicator进行扩展。

2.9.4 自动配置的ReactiveHealthIndicators

在适当的情况下，以下ReactiveHealthIndicators是由Spring Boot自动配置的：

必要时，反应性指标取代常规指标。而且，任何未显式处理的HealthIndicator都是自动包装的

2.10 应用信息

应用程序信息公开从ApplicationContext中定义的所有InfoContributor beans收集的各种信息。 Spring Boot包含许多自动配置的InfoContributor beans，您也可以编写自己的。

2.10.1 自动配置的InfoContributors

适当情况下，以下InfoContributor beans由Spring Boot自动配置：

可以通过设置management.info.defaults.enabled属性来禁用它们。

2.10.2 自定义应用信息

您可以通过设置info.* Spring属性来自定义info端点公开的数据。infokey下的所有Enviroment属性都会自动公开。例如，您可以将以下设置添加到您的application.properties文件中：

info.app.encoding=UTF-8
info.app.java.source=1.8
info.app.java.target=1.8

YAML文件对应设置为

info:
  app:
    encoding:UTF-8
    java.source:1.8
    java.traget:1.8

访问info端口,结果为

{
    "app": "encoding:UTF-8 java.source:1.8 java.traget:1.8"
}

与其对这些值进行硬编码，您还可以在构建时展开信息属性。 假设你使用Maven，你可以重写前面的例子，如下所示：

info.app.encoding=@project.build.sourceEncoding@
info.app.java.source=@java.version@
info.app.java.target=@java.version@

2.10.3 Git提交信息

info端点的另一个有用特性是它能够在构建项目时发布有关git源代码库状态的信息。如果GitProperties bean可用，则会显示git.branch，git.commit.id和git.commit.time属性。

如果git.properties文件在类路径的根目录中可用，则会自动配置GitProperties bean。有关更多详细信息，请参阅“生成git信息”。

如果要显示完整的git信息（即git.properties的完整内容），请使用management.info.git.mode属性，如下所示：

management.info.git.mode=full

2.10.4 构建信息

如果BuildProperties bean可用，info端点还可以发布关于您的构建的信息。如果META-INF/build-info.properties文件在类路径中可用，则会发生这种情况。

Maven和Gradle插件都可以生成该文件。有关更多详细信息，请参阅“生成构建信息”。

2.10.5 编写自定义InfoContributors

为了提供定制的应用程序信息，您可以注册实现InfoContributor接口的Spring bean。 以下示例为单个值提供了一个example条目：

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 ExampleInfoContributor implements InfoContributor {
    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("example",
                Collections.singletonMap("key", "value"));
    }
}

如果您访问info端点，则应该看到包含以下附加条目的响应:

{
    "example": {
        "key" : "value"
    }
}

3. 通过HTTP进行监控和管理

如果您正在开发Web应用程序，Spring Boot Actuator会自动配置所有已启用的端点以通过HTTP进行公开。默认约定是使用以/actuator作为前缀的端点的ID作为URL路径。例如，health被暴露为/actuator/health。

Actuator本身支持Spring MVC，Spring WebFlux和Jersey。

3.1 自定义管理端点路径

有时候，自定义管理端点的前缀非常有用。例如，您的应用程序可能已经将/actuator用于其他目的。您可以使用management.endpoints.web.base-path属性更改管理端点的前缀，如以下示例中所示：

management.endpoints.web.base-path=/manage

前面的application.properties示例将端点从/actuator/{id}更改为/manage/{id}（例如/manage/info）。

除非管理端口已配置为使用不同的HTTP端口公开端点，否则management.endpoints.web.base-path与server.servlet.context-path相关。如果配置了management.server.port，则management.endpoints.web.base-path将与management.server.servlet.context-path相关。

3.2 自定义管理服务器端口

通过使用默认的HTTP端口公开管理端点是基于云的部署的明智选择。但是，如果您的应用程序在您自己的数据中心内运行，则可能希望使用不同的HTTP端口来公开端点。您可以设置management.server.port属性来更改HTTP端口，如以下示例所示：

management.server.port=8081

3.3 配置管理专用SSL

配置为使用自定义端口时，管理服务器也可以使用各种management.server.ssl.*属性配置自己的SSL。例如，通过这样做，管理服务器可通过HTTP使用，而主应用程序使用HTTPS，如以下属性设置所示：

server.port=8443
server.ssl.enabled=true
server.ssl.key-store=classpath:store.jks
server.ssl.key-password=secret
management.server.port=8080
management.server.ssl.enabled=false

或者，主服务器和管理服务器都可以使用SSL，但使用不同的密钥存储区，如下所示：

server.port=8443
server.ssl.enabled=true
server.ssl.key-store=classpath:main.jks
server.ssl.key-password=secret
management.server.port=8080
management.server.ssl.enabled=true
management.server.ssl.key-store=classpath:management.jks
management.server.ssl.key-password=secret

3.4 自定义管理服务器地址

您可以通过设置management.server.address属性来自定义管理端点可用的地址。如果您只想在内部网络或面向操作系统的网络上收听，或只收听本地主机的连接，那么这样做会很有用。

只有当端口与主服务器端口不同时，您才可以监听其他地址。

以下示例application.properties不允许远程管理连接：

management.server.port=8081
management.server.address=127.0.0.1

3.5 禁用HTTP端点

如果您不想通过HTTP公开端点，则可以将管理端口设置为-1，如以下示例所示：

management.server.port=-1