Spring Boot 2.0官方文档之 Actuator

柔情只为你懂 2022-05-27 13:42 303阅读 0赞

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

### 文章目录 ###

*   *  执行器（Actuator）的定义
     *  1. 开启Actuator
     *  2. 端点(Endpoints)
     *   *  2.1 启用端点
         *  2.2 暴露端点
         *  2.3 保护HTTP端点
         *  2.4 配置端点缓存时间
         *  2.5 端点的发现页
         *  2.6 端点的路径
         *  2.7 跨域支持
         *  2.8 实现自定义端点
         *   *  2.8.1 接收输入
             *  2.8.2 自定义Web端点
             *  2.8.3 Servlet端点
             *  2.8.4 控制器端点
         *  2.9 健康信息
         *   *  2.9.1 自动配置的HealthIndicators
             *  2.9.2 编写自定义HealthIndicators
             *  2.9.3 反应性健康指标
             *  2.9.4 自动配置的ReactiveHealthIndicators
         *  2.10 应用信息
         *   *  2.10.1 自动配置的InfoContributors
             *  2.10.2 自定义应用信息
             *  2.10.3 Git提交信息
             *  2.10.4 构建信息
             *  2.10.5 编写自定义InfoContributors
     *  3. 通过HTTP进行监控和管理
     *   *  3.1 自定义管理端点路径
         *  3.2 自定义管理服务器端口
         *  3.3 配置管理专用SSL
         *  3.4 自定义管理服务器地址
         *  3.5 禁用HTTP端点

## 执行器（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=/`

下面的端点都是可用的：

<table> 
 <thead> 
  <tr> 
   <th>ID</th> 
   <th>描述</th> 
   <th>默认启用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>auditevents</td> 
   <td>显示当前应用程序的审计事件信息</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>beans</td> 
   <td>显示一个应用中<code>所有Spring Beans</code>的完整列表</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>conditions</td> 
   <td>显示<code>配置类和自动配置类</code>(configuration and auto-configuration</td> 
   <td>classes)的状态及它们被应用或未被应用的原因</td> 
  </tr> 
  <tr> 
   <td>configprops</td> 
   <td>显示一个所有<code>@ConfigurationProperties</code>的集合列表</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>env</td> 
   <td>显示来自Spring的 <code>ConfigurableEnvironment</code>的属性</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>flyway</td> 
   <td>显示数据库迁移路径，如果有的话</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>health</td> 
   <td>显示应用的<code>健康信息</code>（当使用一个未认证连接访问时显示一个简单</td> 
   <td>的’status’，使用认证连接访问则显示全部信息详情）</td> 
  </tr> 
  <tr> 
   <td>info</td> 
   <td>显示任意的<code>应用信息</code></td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>liquibase</td> 
   <td>展示任何Liquibase数据库迁移路径，如果有的话</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>metrics</td> 
   <td>展示当前应用的<code>metrics</code>信息</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>mappings</td> 
   <td>显示一个所有<code>@RequestMapping</code>路径的集合列表</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>scheduledtasks</td> 
   <td>显示应用程序中的<code>计划任务</code></td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>sessions</td> 
   <td>允许从Spring会话支持的会话存储中检索和删除(retrieval and deletion)</td> 
   <td>用户会话。使用Spring Session对反应性Web应用程序的支持时不可用。</td> 
  </tr> 
  <tr> 
   <td>shutdown</td> 
   <td>允许应用以优雅的方式关闭（默认情况下不启用）</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>threaddump</td> 
   <td>执行一个线程dump</td> 
   <td>Yes</td> 
  </tr> 
 </tbody> 
</table>

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

<table> 
 <thead> 
  <tr> 
   <th>ID</th> 
   <th>描述</th> 
   <th>默认启用</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>heapdump</td> 
   <td>返回一个GZip压缩的<code>hprof</code>堆dump文件</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>jolokia</td> 
   <td>通过HTTP暴露<code>JMX beans</code>（当Jolokia在类路径上时，WebFlux不可用）</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>logfile</td> 
   <td>返回<code>日志文件内容</code>（如果设置了logging.file或logging.path属性的话），支持使用HTTP <strong>Range</strong>头接收日志文件内容的部分信息</td> 
   <td>Yes</td> 
  </tr> 
  <tr> 
   <td>prometheus</td> 
   <td>以可以被Prometheus服务器抓取的格式显示<code>metrics</code>信息</td> 
   <td>Yes</td> 
  </tr> 
 </tbody> 
</table>

> 注意  
> 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 暴露端点 ###

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

<table> 
 <thead> 
  <tr> 
   <th>ID</th> 
   <th>JMX</th> 
   <th>Web</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>auditevents</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>beans</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>conditions</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>configprops</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>env</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>flyway</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>health</td> 
   <td>Yes</td> 
   <td><code>Yes</code></td> 
  </tr> 
  <tr> 
   <td>heapdump</td> 
   <td>N/A</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>httptrace</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>info</td> 
   <td>Yes</td> 
   <td><code>Yes</code></td> 
  </tr> 
  <tr> 
   <td>jolokia</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>logfile</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>loggers</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>liquibase</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>metrics</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>mappings</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>prometheus</td> 
   <td>N/A</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>scheduledtasks</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>sessions</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>shutdown</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
  <tr> 
   <td>threaddump</td> 
   <td>Yes</td> 
   <td>No</td> 
  </tr> 
 </tbody> 
</table>

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

<table> 
 <thead> 
  <tr> 
   <th>Property</th> 
   <th>Default</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>management.endpoints.jmx.exposure.exclude</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>management.endpoints.jmx.exposure.include</td> 
   <td>*</td> 
  </tr> 
  <tr> 
   <td>management.endpoints.web.exposure.exclude</td> 
   <td></td> 
  </tr> 
  <tr> 
   <td>management.endpoints.web.exposure.include</td> 
   <td>info, health</td> 
  </tr> 
 </tbody> 
</table>

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中有特殊的含义，所以如果你想包含（或排除）所有的端点，一定要加引号，如下例所示：
> 
>     management:
>      endpoints:
>        web:
>          exposure:
>            include: '*'
> 
> 如果您的应用程序对外公开，我们强烈建议您保护您的端点,方法见下文。  
> 如果您希望在暴露端点时实施您自己的策略，您可以注册一个`EndpointFilter` bean。

### 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，则需要添加自定义安全配置，以允许对端点进行未经身份验证的访问，如以下示例所示：

### 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`。例如，具有ID`sessions`的端点将使用`/ 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`属性，该属性可以使用以下值之一进行配置：

<table> 
 <thead> 
  <tr> 
   <th>Name</th> 
   <th>Description</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>never</td> 
   <td>细节永远不会显示。</td> 
  </tr> 
  <tr> 
   <td>when-authorized</td> 
   <td>详细信息仅向授权用户显示。授权角色可以使用<code>management.endpoint.health.roles</code>进行配置。</td> 
  </tr> 
  <tr> 
   <td>always</td> 
   <td>详细信息显示给所有用户。</td> 
  </tr> 
 </tbody> 
</table>

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

#### 2.9.1 自动配置的HealthIndicators ####

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

<table> 
 <thead> 
  <tr> 
   <th>Name</th> 
   <th>Description</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>CassandraHealthIndicator</td> 
   <td>检查Cassandra数据库是否启动</td> 
  </tr> 
  <tr> 
   <td>DiskSpaceHealthIndicator</td> 
   <td>检查磁盘空间是否不足。</td> 
  </tr> 
  <tr> 
   <td>DataSourceHealthIndicator</td> 
   <td>检查是否可以获得与DataSource的连接。</td> 
  </tr> 
  <tr> 
   <td>ElasticsearchHealthIndicator</td> 
   <td>检查Elasticsearch集群是否启动。</td> 
  </tr> 
  <tr> 
   <td>InfluxDbHealthIndicator</td> 
   <td>检查InfluxDB服务器是否启动。</td> 
  </tr> 
  <tr> 
   <td>JmsHealthIndicator</td> 
   <td>检查JMS代理是否启动。</td> 
  </tr> 
  <tr> 
   <td>MailHealthIndicator</td> 
   <td>检查邮件服务器是否启动。</td> 
  </tr> 
  <tr> 
   <td>MongoHealthIndicator</td> 
   <td>检查Mongo数据库是否启动。</td> 
  </tr> 
  <tr> 
   <td>Neo4jHealthIndicator</td> 
   <td>检查Neo4j服务器是否启动。</td> 
  </tr> 
  <tr> 
   <td>RabbitHealthIndicator</td> 
   <td>检查Rabbit服务器是否启动。</td> 
  </tr> 
  <tr> 
   <td>RedisHealthIndicator</td> 
   <td>检查Redis服务器是否启动。</td> 
  </tr> 
  <tr> 
   <td>SolrHealthIndicator</td> 
   <td>检查Solr服务器是否已启动。</td> 
  </tr> 
 </tbody> 
</table>

> 您可以通过设置`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。

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

<table> 
 <thead> 
  <tr> 
   <th>Status</th> 
   <th>Mapping</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>DOWN</td> 
   <td>服务不可用 (503)</td> 
  </tr> 
  <tr> 
   <td>OUT_OF_SERVICE</td> 
   <td>服务不可用 (503)</td> 
  </tr> 
  <tr> 
   <td>UP</td> 
   <td>默认情况下没有映射，所以http状态是200</td> 
  </tr> 
  <tr> 
   <td>UNKNOWN</td> 
   <td>默认情况下没有映射，所以http状态是200</td> 
  </tr> 
 </tbody> 
</table>

#### 2.9.3 反应性健康指标 ####

对于反应式应用程序（例如使用Spring WebFlux的应用程序），`ReactiveHealthIndicator`提供了获取应用程序运行状况的非阻塞合同。与传统的`HealthIndicator`类似，健康信息从`ApplicationContext`中定义的所有`ReactiveHealthIndicator`bean中收集。在弹性调度器上包含并执行不检查反应性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自动配置的：

<table> 
 <thead> 
  <tr> 
   <th>Name</th> 
   <th>Description</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>MongoReactiveHealthIndicator</td> 
   <td>检查Mongo数据库是否启动。</td> 
  </tr> 
  <tr> 
   <td>RedisReactiveHealthIndicator</td> 
   <td>检查Redis服务器是否启动。</td> 
  </tr> 
 </tbody> 
</table>

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

### 2.10 应用信息 ###

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

#### 2.10.1 自动配置的InfoContributors ####

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

<table> 
 <thead> 
  <tr> 
   <th>Name</th> 
   <th>Description</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>EnvironmentInfoContributor</td> 
   <td>在<code>info</code>key下显示<code>Environment</code>中的任何key。</td> 
  </tr> 
  <tr> 
   <td>GitInfoContributor</td> 
   <td>如果<code>git.properties</code>文件可用，则显示git信息。</td> 
  </tr> 
  <tr> 
   <td>BuildInfoContributor</td> 
   <td>如果<code>META-INF/build-info.properties</code>文件可用，则公开构建信息。</td> 
  </tr> 
 </tbody> 
</table>

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

#### 2.10.2 自定义应用信息 ####

您可以通过设置`info.*` Spring属性来自定义`info`端点公开的数据。`info`key下的所有`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信息（即`git.properties`的完整内容），请使用`management.info.git.mode`属性，如下所示：

management.info.git.mode=full

#### 2.10.4 构建信息 ####

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

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

#### 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

[HTML]: https://docs.spring.io/spring-boot/docs/2.0.1.RELEASE/actuator-api//html
[PDF]: https://docs.spring.io/spring-boot/docs/2.0.1.RELEASE/actuator-api//pdf/spring-boot-actuator-web-api.pdf
[CorsEndpointProperties]: https://github.com/spring-projects/spring-boot/tree/v2.0.1.RELEASE/spring-boot-project/spring-boot-actuator-autoconfigure/src/main/java/org/springframework/boot/actuate/autoconfigure/endpoint/web/CorsEndpointProperties.java
[git]: https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#howto-git-info
[Link 1]: https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#howto-build-info