服务监控 Spring Boot Actuator 介绍

1. 概述

在本文中，我们将介绍Spring Boot Actuator。首先介绍一些Actuator的基础知识，然后详细讨论Spring Boot 1.x与2.x中的用法和不同点。

我们将学习如何在Spring Boot 1.x中使用，配置和扩展此监视工具。然后，我们将讨论如何使用Boot 2.x和WebFlux利用反应式编程模型来做同样的事情。

Spring Boot Actuator自2014年4月开始推出，同时还推出了第一个Spring Boot版本。

随着Spring Boot 2的发布，Actuator也经过了重新设计，并添加了一些新的令人兴奋的终端。

本指南分为3个主要部分：

• 什么是Actuator？
• Spring Boot 1.x中的Actuator
• Spring Boot 2.x中的Actuator

2. 什么是Actuator？

从本质上讲，Actuator为我们能检测应用程序是否生产就绪的能力。

通过这种依赖关系监控我们的应用程序，收集指标，了解流量或数据库的状态变得简单易行。

这个库的主要好处是我们可以获得生产级的工具，而无需自己实际实现这些功能。

Actuator主要用于公开有关正在运行的应用程序的运行信息 - 运行状况，指标，信息，转储，env等等。它使用HTTP端点或JMX bean来使我们能够与它进行交互。

一旦这个依赖关系放在类路径上，就可以开箱即用几个预制端点。与大多数Spring模块一样，我们可以通过多种方式轻松配置或扩展它。

2.1 入门

要启用Spring Boot Actuator，我们只需要将spring-boot-actuator依赖项添加到我们的包管理器中。在Maven：

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

请注意，无论Boot版本如何，这都保持有效，因为会在Spring Boot Bill of Materials（BOM）中指定版本。

3. Spring Boot 1.x版本

在1.x中，Actuator遵循 R/W 模型，这意味着我们可以从中读取或写入它。例如，我们可以检索指标或应用程序的运行状况。或者，我们可以优雅地终止我们的应用程序或更改我们的日志配置。

为了使其工作，Actuator要求Spring MVC通过HTTP公开其端点。不需要其他的技术支持。

3.1 端点

在1.x中，Actuator有自己的安全模型。它利用Spring Security构造，但需要独立于应用程序进行配置。

此外，大多数端点都是敏感的 - 这意味着它们不是完全公开的，换句话说，大多数信息都会被省略 - 而少数端点不是，比如 /info。

以下是Boot提供的一些最常见的端点：

• /health - 显示应用程序运行状况信息（通过未经身份验证的连接访问时的简单“状态”或经过身份验证时的完整详细信息）; 它默认不敏感
• /info -显示任意应用程序信息; 默认情况下不敏感
• /metrics -显示当前应用程序的“指标”信息; 它默认是敏感
• /trace -显示跟踪信息（默认情况下是最后几个HTTP请求）

我们可以在官方文档中找到现有端点的完整列表。

3.2 配置现有端点

可以使用以下格式使用属性自定义每个端点：

端点.[端点名称].[要定制的属性]

其中有三个属性：

• id -通过HTTP访问此端点
• enabled - 如果为true，则可以访问，否则不能访问
• sensitive - 如果是，则需要授权通过HTTP显示关键信息

例如，添加以下属性将自定义/beans端点：

endpoints.beans.id=springbeans
endpoints.beans.sensitive=false
endpoints.beans.enabled=true

3.3 /health端点

该端点被用来检查正在运行的应用程序的运行状况或状态。它通常由监控软件执行，以提醒我们运行的实例是否因其他原因而关闭或变得不健康。例如：我们的数据库连接问题，磁盘空间不足......

默认情况下，当通过HTTP进行未经授权的访问仅显示健康信息

{
    "status" : "UP"
}

此健康信息是从实现我们的应用程序上下文中配置的HealthIndicator接口的bean中收集的。

HealthIndicator返回的一些信息本质上是敏感的 - 但是我们可以通过配置endpoints.health.sensitive = false来公开更详细的信息，如磁盘空间，消息代理连接，自定义检查等。

我们还可以实现自己的自定义运行状况指示器 - 它可以收集特定于应用程序的任何类型的自定义运行状况数据，并通过/ health端点自动公开它：

@Component
public class HealthCheck 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();
    }
     
    public int check() {
        // Our logic to check health
        return 0;
    }
}

以下是输出的内容：

{
    "status" : "DOWN",
    "myHealthCheck" : {
        "status" : "DOWN",
        "Error Code" : 1
     },
     "diskSpace" : {
         "status" : "UP",
         "free" : 209047318528,
         "threshold" : 10485760
     }
}

3.4 /info端点

我们还可以自定义/info端点显示的数据- 例如：

info.app.name=Spring Sample Application
info.app.description=This is my first spring boot application
info.app.version=1.0.0

输出示例：

{
    "app" : {
        "version" : "1.0.0",
        "description" : "This is my first spring boot application",
        "name" : "Spring Sample Application"
    }
}

3.5 /metrics端点

metrics端点发布有关OS，JVM以及应用程序级别度量的信息。一旦启用，我们就会获得内存，堆，处理器，线程，加载的类，卸载的类，线程池以及一些HTTP指标等信息。

以下是此端点的输出开箱即用的内容：

{
    "mem" : 193024,
    "mem.free" : 87693,
    "processors" : 4,
    "instance.uptime" : 305027,
    "uptime" : 307077,
    "systemload.average" : 0.11,
    "heap.committed" : 193024,
    "heap.init" : 124928,
    "heap.used" : 105330,
    "heap" : 1764352,
    "threads.peak" : 22,
    "threads.daemon" : 19,
    "threads" : 22,
    "classes" : 5819,
    "classes.loaded" : 5819,
    "classes.unloaded" : 0,
    "gc.ps_scavenge.count" : 7,
    "gc.ps_scavenge.time" : 54,
    "gc.ps_marksweep.count" : 1,
    "gc.ps_marksweep.time" : 44,
    "httpsessions.max" : -1,
    "httpsessions.active" : 0,
    "counter.status.200.root" : 1,
    "gauge.response.root" : 37.0
}

为了收集自定义指标，我们支持“gauges”，即数据的单值快照和“计数器”，即递增/递减指标。

让我们在/metrics端点中实现我们自己的自定义指标。例如，我们将自定义登录流程以记录成功和失败的登录尝试：

@Service
public class LoginServiceImpl {
 
    private final CounterService counterService;
     
    public LoginServiceImpl(CounterService counterService) {
        this.counterService = counterService;
    }
     
    public boolean login(String userName, char[] password) {
        boolean success;
        if (userName.equals("admin") && "secret".toCharArray().equals(password)) {
            counterService.increment("counter.login.success");
            success = true;
        }
        else {
            counterService.increment("counter.login.failure");
            success = false;
        }
        return success;
    }
}

这是输出的样子：

{
    ...
    "counter.login.success" : 105,
    "counter.login.failure" : 12,
    ...
}

请注意，登录尝试和其他安全相关事件在Actuator中可用作审计事件。

3.6 创建新端点

除了使用Spring Boot提供的现有端点之外，我们还可以创建一个全新的端点。

首先，我们需要让新端点实现Endpoint<T>接口：

@Component
public class CustomEndpoint implements Endpoint<List<String>> {
     
    @Override
    public String getId() {
        return "customEndpoint";
    }
 
    @Override
    public boolean isEnabled() {
        return true;
    }
 
    @Override
    public boolean isSensitive() {
        return true;
    }
 
    @Override
    public List<String> invoke() {
        // Custom logic to build the output
        List<String> messages = new ArrayList<String>();
        messages.add("This is message 1");
        messages.add("This is message 2");
        return messages;
    }
}

为了访问这个新端点，它的id用于映射它，即我们可以运行它/customEndpoint。

输出：

[ "This is message 1", "This is message 2" ]

3.7 进一步定制

出于安全考虑，我们可能会选择通过非标准端口公开Actuator端点 - 可以轻松地使用management.port属性来配置它。

另外，正如我们已经提到的，在1.x. Actuator基于Spring Security配置自己的安全模型，但独立于应用程序的其余部分。

因此，我们可以更改management.address属性以限制可以通过网络访问端点的位置：

#port used to expose actuator
management.port=8081 
 
#CIDR allowed to hit actuator
management.address=127.0.0.1 
 
#Whether security should be enabled or disabled altogether
management.security.enabled=false

此外，除/info之外的所有内置端点默认都是敏感的。如果应用程序使用的是Spring Security，我们可以通过在application.properties文件中定义默认安全属性（用户名，密码和角色）来保护这些端点：

security.user.name=admin
security.user.password=secret
management.security.role=SUPERUSER

4. Spring Boot 2.x版本

2.x中Actuator保持其基本意图，但简化了其模型，扩展功能并包含更好的默认值。

首先，这个版本变得与技术无关。此外，它通过将其与应用程序合并来简化其安全模型。

最后，在各种变化中，重要的是要记住其中一些变化正在破碎：这包括HTTP请求/响应以及Java API。

此外，最新版本现在支持CRUD模型，而不是旧的RW（读/写）模型。

4.1 技术支持

在2.X版本中Actuator现在与技术无关，而在1.x中，它与MVC相关联，因此与Servlet API相关联。

在2.x中，Actuator定义了它的模型，可插拔和可扩展，而不依赖于MVC。

因此，通过这个新模型，我们可以利用MVC和WebFlux作为底层Web技术。

此外，可以通过实施正确的适配器来扩充新的技术。

最后，JMX仍然支持在没有任何其他代码的情况下公开端点。

4.2 重要变化

与以前的版本不同，Actuator禁用了大多数端点。

因此，默认情况下只有两个可用/health和/info。

如果我们想要启用所有这些，我们可以设置management.endpoints.web.exposure.include = *。或者，我们可以列出应该启用的某个端点。

Actuator现在与常规App安全规则共享安全配置。因此，安全模型被大大简化。

要调整Actuator安全规则，我们可以为/actuator/**添加一个条目：

@Bean
public SecurityWebFilterChain securityWebFilterChain(
  ServerHttpSecurity http) {
    return http.authorizeExchange()
      .pathMatchers("/actuator/**").permitAll()
      .anyExchange().authenticated()
      .and().build();
}

我们可以找到有关全新Actuator官方文档的更多详细信息。

此外，默认情况下，所有执行器端点现在都位于/actuator 路径下。

与前一版本相同，我们可以使用属性management.endpoints.web.base-path调整此路径。

4.3 预定义的端点

我们来看看一些可用的端点，其中大部分已经在1.x中可用。同时也有些变化，添加了一些端点，一些已删除，一些已重组：

• /auditevents -列出与安全审计相关的事件，例如用户登录/注销。此外，我们可以按主要或类型等字段进行过滤。
• /beans -在我们的BeanFactory中使用所有可用的bean 。与/ auditevents不同，它不支持过滤。
• /conditions -以前称为/autoconfig，构建有关自动配置的条件报告。
• /configprops -允许我们获取所有@ConfigurationProperties bean。
• /env -返回当前环境属性。此外，我们可以检索单个属性。
• /flyway -提供有关我们的Flyway数据库迁移的详细信息。
• /health -总结了我们的应用程序的健康状态。
• /heapdump -从我们的应用程序使用的JVM构建并返回堆转储。
• /info -返回一般信息。它可能是自定义数据，构建信息或有关最新提交的详细信息。
• /liquibase - 类似于 /flyway但是是针对Liquibase的。
• /logfile -返回普通的应用程序日志。
• /loggers -使我们能够查询和修改应用程序的日志记录级别。
• /metrics -详细说明我们的应用程序的指标。这可能包括通用指标和自定义指标。
• /prometheus -返回与上一个类似的指标，但格式化为与Prometheus服务器一起使用。
• /scheduledtasks -提供有关应用程序中每个计划任务的详细信息。
• /sessions -列出我们正在使用Spring Session的HTTP会话。
• /shutdown -正常关闭应用程序。
• /threaddump -转储底层JVM的线程信息。

4.4 健康指标

与以前的版本一样，我们可以轻松添加自定义指标。与其他API相反，创建自定义健康端点的抽象保持不变。但是，添加了新的接口ReactiveHealthIndicator以实现响应式运行状况检查。

我们来看一个简单的自定义反应健康检查：

@Component
public class DownstreamServiceHealthIndicator implements ReactiveHealthIndicator {
 
    @Override
    public Mono<Health> health() {
        return checkDownstreamServiceHealth().onErrorResume(
          ex -> Mono.just(new Health.Builder().down(ex).build())
        );
    }
 
    private Mono<Health> checkDownstreamServiceHealth() {
        // we could use WebClient to check health reactively
        return Mono.just(new Health.Builder().up().build());
    }
}

健康指标的一个便利功能是我们可以将它们聚合为层次结构的一部分。因此，按照前面的示例，我们可以将所有下游服务分组到下游服务类别下。只要每个嵌套服务都可以访问，此类别就是健康的。

复合运行状况检查通过CompositeHealthIndicator存在于1.x中。此外，在2.x中，我们可以将CompositeReactiveHealthIndicator用于其反应对应物。

与Spring Boot 1.x不同，endpoints.<id>.sensitive标签已被删除。要隐藏完整的健康报告，我们可以利用新的management.endpoint.health.show-details。默认情况下，此标签为false。

4.5 Spring Boot 2中的度量标准

在Spring Boot 2.0中，内部指标被Micrometer支持取代。因此，我们可以期待突破性变化。如果我们的应用程序使用GaugeService或CounterService等度量服务，它们将不再可用。

相反，我们希望直接与Micrometer交互。在Spring Boot 2.0中，我们将为我们自动配置一个MeterRegistry类型的bean 。

此外，Micrometer现在是Actuator依赖的一部分。因此，只要Actuator依赖项在类路径中，我们就可以继续工作。

此外，我们将从/metrics端点获得一个全新的响应：

{
  "names": [
    "jvm.gc.pause",
    "jvm.buffer.memory.used",
    "jvm.memory.used",
    "jvm.buffer.count",
    // ...
  ]
}

正如我们在前面的例子中所观察到的那样，我们在1.x中没有实际的指标。

要获取特定指标的实际值，我们现在可以导航到所需的指标，即/actuator/metrics/jvm.gc.pause并获得详细响应：

{
  "name": "jvm.gc.pause",
  "measurements": [
    {
      "statistic": "Count",
      "value": 3.0
    },
    {
      "statistic": "TotalTime",
      "value": 7.9E7
    },
    {
      "statistic": "Max",
      "value": 7.9E7
    }
  ],
  "availableTags": [
    {
      "tag": "cause",
      "values": [
        "Metadata GC Threshold",
        "Allocation Failure"
      ]
    },
    {
      "tag": "action",
      "values": [
        "end of minor GC",
        "end of major GC"
      ]
    }
  ]
}

我们可以看到，现在的指标要详细得多。不仅包括不同的值，还包括一些相关的元数据。

4.6 自定义/info端点

该/info端点保持不变。和以前一样，我们可以使用Maven或Gradle各自的依赖项添加git细节：

<dependency>
    <groupId>pl.project13.maven</groupId>
    <artifactId>git-commit-id-plugin</artifactId>
</dependency>

同样，我们还可以使用Maven或Gradle插件包含构建信息，包括name，group和version：

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>build-info</goal>
            </goals>
        </execution>
    </executions>
</plugin>

4.7 创建自定义端点

正如我们之前所指出的，我们可以创建自定义端点。但是，Spring Boot 2重新设计了实现此目的的方式，以支持新技术无关的特点。

让我们创建一个Actuator端点来查询，启用和禁用我们应用程序中的功能标志：

@Component
@Endpoint(id = "features")
public class FeaturesEndpoint {
 
    private Map<String, Feature> features = new ConcurrentHashMap<>();
 
    @ReadOperation
    public Map<String, Feature> features() {
        return features;
    }
 
    @ReadOperation
    public Feature feature(@Selector String name) {
        return features.get(name);
    }
 
    @WriteOperation
    public void configureFeature(@Selector String name, Feature feature) {
        features.put(name, feature);
    }
 
    @DeleteOperation
    public void deleteFeature(@Selector String name) {
        features.remove(name);
    }
 
    public static class Feature {
        private Boolean enabled;
 
        // [...] getters and setters 
    }
 
}

要获得端点，我们需要一个bean。在我们的示例中，我们正在使用@Component。另外，我们需要用@Endpoint来装饰这个bean 。

我们的端点的路径由@Endpoint的id参数决定，在我们的例子中，它将请求路由到/actuator/features。

准备好之后，我们可以开始使用以下命

• @ReadOperation -它将映射到HTTP GET
• @WriteOperation - 它将映射到HTTP POST
• @DeleteOperation - 它将映射到HTTP DELETE

当我们在应用程序中运行应用程序访问上面的端点时，Spring Boot将注册它。

验证这一点的一种快速方法是检查日志：

[...].WebFluxEndpointHandlerMapping: Mapped "{[/actuator/features/{name}],
  methods=[GET],
  produces=[application/vnd.spring-boot.actuator.v2+json || application/json]}"
[...].WebFluxEndpointHandlerMapping : Mapped "{[/actuator/features],
  methods=[GET],
  produces=[application/vnd.spring-boot.actuator.v2+json || application/json]}"
[...].WebFluxEndpointHandlerMapping : Mapped "{[/actuator/features/{name}],
  methods=[POST],
  consumes=[application/vnd.spring-boot.actuator.v2+json || application/json]}"
[...].WebFluxEndpointHandlerMapping : Mapped "{[/actuator/features/{name}],
  methods=[DELETE]}"[...]

在之前的日志中，我们可以看到WebFlux如何公开我们的新端点。我们想要切换到MVC，只需委托该技术而无需更改任何代码。

此外，我们还有一些重要的考虑因素要记住这种新方法：

• MVC没有依赖关系
• 作为方法之前存在的所有元数据（敏感，启用...）不再存在。但是，我们可以使用@Endpoint启用或禁用端点（id =“features”，enableByDefault = false）
• 与1.x不同，不再需要扩展给定的接口
• 与旧的Read / Write模型相比，现在我们可以使用@DeleteOperation定义DELETE操作

4.8 扩展现有端点

让我们假设我们想要确保我们的应用程序的生产实例永远不是SNAPSHOT版本。我们决定通过更改返回此信息的Actuator端点的HTTP状态代码（即/ info）来完成此操作。如果我们的应用程序恰好是一个快照。我们将获得不同的HTTP状态代码。

我们可以使用@EndpointExtension注释或其更具体的特化@EndpointWebExtension或@EndpointJmxExtension 轻松扩展预定义端点的行为：

@Component
@EndpointWebExtension(endpoint = InfoEndpoint.class)
public class InfoWebEndpointExtension {
 
    private InfoEndpoint delegate;
 
    // standard constructor
 
    @ReadOperation
    public WebEndpointResponse<Map> info() {
        Map<String, Object> info = this.delegate.info();
        Integer status = getStatus(info);
        return new WebEndpointResponse<>(info, status);
    }
 
    private Integer getStatus(Map<String, Object> info) {
        // return 5xx if this is a snapshot
        return 200;
    }
}

4.9 启用所有端点

为了使用HTTP访问Actuator端点，我们需要启用和公开它们。默认情况下，除了/shutdown之外所有端点是启用的。只有 /health和/info端点默认情况下是暴露出来的。

我们需要添加以下配置来公开所有端点：

management.endpoints.web.exposure.include=*

要显式启用特定端点（例如 /shutdown）， 我们使用：

management.endpoint.shutdown.enabled=true

要公开所有已启用端点而除去某一个特定以外的（例如/loggers），我们使用：

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=loggers

5. 总结

在本文中，我们讨论了Spring Boot Actuator。我们开始定义Actuator的含义以及它对我们的作用。

接下来，我们专注于当前Spring Boot 1.x版本的Actuator。讨论如何使用它，调整它的延伸。

然后，我们在Spring Boot 2中讨论了Actuator。我们专注于什么是新的，我们利用WebFlux来暴露我们的端点。

此外，我们讨论了在这个新迭代中我们可以看到的重要安全性变化。我们讨论了一些流行的端点以及它们如何发生变化。

最后，我们演示了如何定制和扩展Actuator。