Spring Boot 探索 | Actuator 端点详细说明

先在这里声明一下：这一系列的文章都是自己查询网上资料学习而来，不可避免有些内容从其他地方copy过来，如有侵犯请联系我删除，谢谢！（引用部分都会添加注脚）

本系列文章的写作环境为：Spring Boot 2.0.7.RELEASE、JDK 1.8.0_131、IntelliJ IDEA ULTIMATE 2018.1。并没有使用最新版本的Spring Boot进行学习，新版本还不稳定，存在很多问题，不要把时间花费在无谓的BUG上。

接上文……，这篇文章我们详细的说明一下 Actuator 内置的端点。

Endpoints（端点）介绍

---

Endpoints 是 Actuator 的核心部分，它用来监视应用程序及交互，spring-boot-actuator中已经内置了非常多的Endpoints（health、info、beans、httptrace、shutdown等等），同时也允许我们扩展自己的端点。

Endpoints 分成两类：原生端点和用户自定义端点；自定义端点主要是指扩展性，用户可以根据自己的实际应用，定义一些比较关心的指标，在运行期进行监控。

原生端点是在应用程序里提供的众多 restful api 接口，通过它们可以监控应用程序运行时的内部状况。原生端点又可以分成三类：

• 应用配置类：可以查看应用在运行期间的静态信息：例如自动配置信息、加载的spring bean信息、yml文件配置信息、环境信息、请求映射信息；
• 度量指标类：主要是运行期间的动态信息，例如堆栈、请求连、一些健康指标、metrics信息等；
• 操作控制类：主要是指shutdown，用户可以发送一个请求将应用的监控功能关闭。

Actuator 默认提供了以下接口，具体如下表所示：

ID	描述	默认启用	默认公开
auditevents	公开当前应用程序的审计事件信息	Yes	No
beans	显示应用程序中所有Spring bean的完整列表	Yes	No
conditions	显示在配置和自动配置类上评估的条件以及它们是否匹配的原因	Yes	No
configprops	显示所有@ConfigurationProperties对照的列表	Yes	No
env	从Spring的ConfigurableEnvironment中公开属性	Yes	No
flyway	显示已应用的任何Flyway数据库迁移	Yes	No
health	显示应用程序健康信息	Yes	Yes
httptrace	显示HTTP跟踪信息（默认情况下，最后100个HTTP请求-响应交互）	Yes	No
info	显示任意应用程序信息	Yes	Yes
loggers	显示和修改应用程序中记录器的配置	Yes	No
liquibase	显示已应用的任何Liquibase数据库迁移	Yes	No
metrics	显示当前应用程序的“指标”信息	Yes	No
mappings	显示所有@RequestMapping路径对照的列表	Yes	No
scheduledtasks	显示应用程序中调度的任务	Yes	No
sessions	允许从Spring Session支持的会话存储中检索和删除用户会话	Yes	No
shutdown	让应用程序优雅地关闭	No	No
threaddump	执行线程转储	Yes	No

如果你的应用程序是一个web应用程序（Spring MVC、Spring WebFlux或Jersey），你可以使用以下附加端点：

ID	描述	默认启用	默认公开
heapdump	返回一个GZip压缩的hprof堆转储文件	Yes	No
jolokia	在HTTP上公开JMX bean（当Jolokia在类路径上时，WebFlux不可用）	Yes	No
logfile	返回日志文件的内容，支持使用HTTP Range header来检索日志文件内容的一部分	Yes	No
prometheus	公开指标，该格式可以被Prometheus服务器采集	Yes	No

需要注意的是：

• Spring Boot 2.0的端点和之前的版本有较大不同，使用时需注意。另外，端点的监控机制也有很大不同，启用了不代表可以直接访问，还需要将其暴露出来；
• 传统的management.security管理已被标记为不推荐，现在一般使用单独启用并暴露；
• 禁用的端点将从应用程序上下文中完全删除，如果只想公开端点(对外暴露)，需要使用include和exclude属性属性。

要查看所有的内置端点，我们需要在 application.yml 文件中添加如下配置项，启用并暴露所有端口：

management:
  endpoints:
    web:
      exposure:
        include: "*" # 暴露所有端口
    enabled-by-default: true # 启用所有端口

访问 /actuator 端点，可以获取所有启用并暴露的端点：http://127.0.0.1:8080/actuator

{
  "_links": {
    "self": {
      "href": "http://127.0.0.1:8080/actuator",
      "templated": false
    },
    
	......
	
    "beans": {
      "href": "http://127.0.0.1:8080/actuator/beans",
      "templated": false
    },
    "health": {
      "href": "http://127.0.0.1:8080/actuator/health",
      "templated": false
    },
    "conditions": {
      "href": "http://127.0.0.1:8080/actuator/conditions",
      "templated": false
    },
	
	......
	
  }
}

Actuator 在 1.X 和 2.X 之间变化很大，具体可以看我的这篇文章：4.2.3 Actuator 在 Spring Boot 1.X 和Spring Boot 2.X 的差异

应用配置类端点

---

由于Spring Boot为了改善传统 Spring 应用繁杂的配置内容，采用了包扫描和自动化配置的机制来加载原本集中于 xml 文件中的各项内容。虽然这样的做法，让我们的代码变得非常简洁，但是整个应用的实例创建和依赖关系等信息都被离散到了各个配置类的注解上，这使得我们分析整个应用中资源和实例的各种关系变得非常的困难。而这类端点就可以帮助我们轻松的获取一系列关于 Spring 应用配置内容的详细报告，比如：自动化配置的报告、Bean创建的报告、环境属性的报告等。¹

/conditions

---

该端点在 1.x 版本中叫 autoconfig，该端点用来获取应用的自动化配置报告。其中，包括所有自动化配置的候选项。同时还列出了每个候选项自动化配置的各个先决条件是否满足。所以，该端点可以帮助我们方便的找到一些自动化配置为什么没有生效的具体原因。该报告内容将自动化配置内容分为三部分：

• positiveMatches：返回的是条件匹配成功的自动化配置；
• negativeMatches：返回的是条件匹配不成功的自动化配置；
• unconditionalClasses；

{
  "positiveMatches": {
    "EndpointWebMvcAutoConfiguration": [
      {
        "condition": "OnClassCondition",
        "message": "@ConditionalOnClass classes found: javax.servlet.Servlet,org.springframework.web.servlet.DispatcherServlet"
      },
      {
        "condition": "OnWebApplicationCondition",
        "message": "found web application StandardServletEnvironment"
      }
    ],
    ......
  },
  "negativeMatches": {
    "HealthIndicatorAutoConfiguration.DataSourcesHealthIndicatorConfiguration": [
      {
        "condition": "OnClassCondition",
        "message": "required @ConditionalOnClass classes not found: org.springframework.jdbc.core.JdbcTemplate"
      }
    ],
    ......
  }
}

从如上示例中我们可以看到，每个自动化配置候选项中都有一系列的条件，比如上面没有成功匹配的HealthIndicatorAutoConfiguration.DataSourcesHealthIndicatorConfiguration配置，它的先决条件就是需要在工程中包含org.springframework.jdbc.core.JdbcTemplate类。由于我们没有引入相关的依赖，它就不会执行自动化配置内容。所以，当我们发现有一些期望的配置没有生效时，就可以通过该端点来查看没有生效的具体原因。

/beans

---

该端点用来获取应用上下文中创建的所有Bean。

如上示例中，我们可以看到在每个bean中都包含了下面这几个信息：

• 外层的key是Bean的名称；
• scope：Bean的作用域；
• type：Bean的Java类型；
• reource：class文件的具体路径；
• dependencies：依赖的Bean名称。

/configprops

---

该端点用来获取应用中配置的属性信息报告，prefix属性代表了属性的配置前缀，properties代表了各个属性的名称和值，例如我们可以设置spring.http.encoding.charset=”UTF-8” 。

/env 和 /env/{toMatch}

---

该端点与 /configprops 不同，它用来获取应用所有可用的环境属性报告。包括：环境变量、JVM属性、应用的配置配置、命令行中的参数。从下面该端点返回的示例片段中，我们可以看到它不仅返回了应用的配置属性，还返回了系统属性、环境变量等丰富的配置信息，其中也包括了应用还没有使用的配置。所以它可以帮助我们方便地看到当前应用可以加载的配置信息，并配合@ConfigurationProperties注解将它们引入到我们的应用程序中来进行使用。另外，为了配置属性的安全，对于一些类似密码等敏感信息，该端点都会进行隐私保护，但是我们需要让属性名中包含：password、secret、key这些关键词，这样该端点在返回它们的时候会使用*来替代实际的属性值。²

/env 是返回所有的环境参数，如果只是查看其中一个的只需要在后边加上参数名称即可。如：http://127.0.0.1:8080/actuator/env/local.server.port

/mappings

---

显示所有的@RequestMapping路径。

{
  "handler": "public java.lang.String com.lpf.actuator.DemoController.index()",
  "predicate": "{[/index],methods=[GET]}",
  "details": {
    "handlerMethod": {
      "className": "com.lpf.actuator.DemoController",
      "name": "index",
      "descriptor": "()Ljava/lang/String;"
    },
    "requestMappingConditions": {
      "consumes": [],
      "headers": [],
      "methods": [
        "GET"
      ],
      "params": [],
      "patterns": [
        "/index"
      ],
      "produces": []
    }
  }
}

/info

---

该端点用来返回一些应用自定义的信息。默认情况下，该端点只会返回一个空的json内容。我们可以在 application.yml 配置文件中通过info前缀来设置一些属性。另外，还有关于应用内部的一些信息，这些信息从编译文件比如：META-INF/build-info.properties 或者 Git 文件比如：git.properties 或者任何环境的 property 中获取。

深度解析：https://blog.csdn.net/qq_26000415/article/details/79234812
使用案例: https://blog.csdn.net/dyc87112/article/details/73739530

操作控制类端点

---

控制类端点拥有强大的控制能力，如果要使用它们的话，需要通过属性来配置开启。

/shutdown

---

在原生端点中，提供了一个用来关闭应用的端点：/shutdown（默认是关闭的）。我们可以通过如下配置开启它：management.endpoint.shutdown.enabled=true。在配置了上述属性之后，只需要访问该应用的/shutdown端点就能实现关闭该应用的远程操作。由于开放关闭应用的操作本身是一件非常危险的事，所以真正在线上使用的时候，我们需要对其加入一定的保护机制，比如：定制Actuator的端点路径、整合Spring Security进行安全校验等。

度量指标类

---

上面我们所介绍的应用配置类端点所提供的信息报告在应用启动的时候都已经基本确定了其返回内容，可以说是一个静态报告。而度量指标类端点提供的报告内容则是动态变化的，这些端点提供了应用程序在运行过程中的一些快照信息，比如：内存使用情况、HTTP请求统计、外部资源指标等。这些端点对于我们构建微服务架构中的监控系统非常有帮助，由于Spring Boot应用自身实现了这些端点，所以我们可以很方便地利用它们来收集我们想要的信息，以制定出各种自动化策略。下面，我们就来分别看看这些强大的端点功能。²

/metrics 和 /metrics/{requiredMetricName}

---

该端点用来返回当前应用的各类重要度量指标，比如：内存信息、线程信息、垃圾回收信息等。

这一对端点不像前边的几对端点，这一对端点中 /metrics 返回所有你能查看的度量指标，/metrics/{requiredMetricName} 是看某一个度量指标的具体值。例如：/actuator/metrics/jvm.buffer.memory.used

Metrics的可视化： Spring Boot Metrics监控之Prometheus&Grafana

/health

---

该端点用来获取应用的各类健康指标信息。在 spring-boot-starter-actuator 模块中自带实现了一些常用资源的健康指标检测器。这些检测器都通过 HealthIndicator 接口实现，并且会根据依赖关系的引入实现自动化装配，比如用于检测磁盘的 DiskSpaceHealthIndicator、检测 DataSource 连接是否可用的 DataSourceHealthIndicator 等。

/httptrace

---

该端点用来返回基本的HTTP跟踪信息。默认情况下，跟踪信息的存储采用org.springframework.boot.actuate.trace.InMemoryTraceRepository实现的内存方式，始终保留最近的100条请求记录。

/auditevents

---

显示应用暴露的审计事件 (比如认证进入、订单失败)

loggers 和 /loggers/{name}³

---

显示和修改配置的loggers。它展示了应用中可配置的loggers的列表和相关的日志等级。

你同样能够使用 /loggers/{name} 来展示特定logger的细节。例如，你可以使用 /loggers/ROOT：

/loggers 这个端点不止可以查看 Logger 等级，还可以修改运行时 Logger 的等级。例如，你可以用 POST 调用/loggers/ROOT ，并传递如下参数:

{
  "configuredLevel": "DEBUG"
}

我们再回过头来查看 ROOT 的 Loggers 等级时，已经修改为如下状态：

/heapdump

---

返回一个GZip压缩的JVM堆dump。

• 介绍HeapDumpWebEndpoint原理: https://www.jianshu.com/p/6df45fed02fa
• 分析dump文件： https://www.cnblogs.com/liangzs/p/8489321.html
• 分析dump文件： https://blog.csdn.net/albertfly/article/details/78686408
• 分析dump文件： https://www.javatang.com/archives/2017/10/30/53562102.html
• 分析dump文件： https://www.cnblogs.com/toSeeMyDream/p/7151635.html

/threaddump

---

执行一个线程dump。

分析工具和方法: https://blog.csdn.net/hivon/article/details/8331350

/scheduledtasks

---

显示应用中的调度任务。

---

1. Spring Boot Actuator监控端点小结 ↩︎

2. Spring Boot入门教程(三十三): Actuator ↩︎ ↩︎

3. Spring Boot Actuator [监控与管理] ↩︎