什么是 Spring Boot Actuator？如何在 Spring Boot 中使用 Actuator？_spring-boot-starter-actuator

当我们在开发和部署应用程序时，监控应用程序的健康状况和性能是非常重要的。Spring Boot Actuator 为我们提供了一组现成的端点（endpoints），可以让我们方便地监控和管理应用程序。在本文中，我们将了解 Spring Boot Actuator 的基本概念和使用方法，并演示如何使用 Actuator 来监控应用程序的健康状况和性能。

什么是 Spring Boot Actuator？

Spring Boot Actuator 是 Spring Boot 提供的用于监控和管理应用程序的模块。它提供了一组现成的端点，可以让我们方便地监控和管理应用程序。这些端点包括健康状况、性能指标、配置信息、日志等。通过这些端点，我们可以了解应用程序的运行状况，及时发现和解决问题，提高应用程序的可用性和可维护性。

Spring Boot Actuator 默认情况下已经集成在 Spring Boot 中，我们只需要在应用程序中添加依赖，并配置一些参数即可使用。下面是一个使用 Spring Boot Actuator 的示例。

如何在 Spring Boot 中使用 Actuator？

要在 Spring Boot 中使用 Actuator，我们需要在应用程序中添加 spring-boot-starter-actuator 依赖。可以在 Maven 或 Gradle 的构建文件中添加以下依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
1
2
3
4

在 Gradle 中，可以使用以下依赖：

implementation 'org.springframework.boot:spring-boot-starter-actuator'
1

添加依赖后，我们需要配置 Actuator 的一些参数。可以在 application.yml 或 application.properties 文件中添加以下配置：

management:
  endpoints:
    web:
      exposure:
        include: "*"
1
2
3
4
5

上面的配置将所有 Actuator 的端点都暴露出来，以便我们可以使用它们来监控应用程序的健康状况和性能指标。我们也可以选择只暴露一部分端点，以便控制访问权限和保护应用程序的安全性。

Actuator 端点的使用

在添加依赖和配置参数之后，我们就可以开始使用 Actuator 端点来监控应用程序的健康状况和性能指标了。Spring Boot Actuator 提供了多个端点，每个端点都提供了不同的功能。在下面的示例中，我们将演示如何使用一些常见的端点来监控应用程序的健康状况和性能指标。

健康状况端点

健康状况端点（health endpoint）用于获取应用程序的健康状况。它可以告诉我们应用程序是否正常运行，以及是否存在任何问题。默认情况下，健康状况端点返回一个简单的 JSON 响应，其中包含应用程序的健康状况信息。

为了访问健康状况端点，我们可以使用以下 URL：

http://localhost:8080/actuator/health
1

在默认情况下，健康状况端点返回的 JSON 响应如下所示：

{
  "status": "UP"
}
1
2
3

这表示应用程序的健康状况正常。如果应用程序存在问题，健康状况端点将返回其他状态，例如：

{
  "status": "DOWN",
  "details": {
    "database": {
      "status": "DOWN",
      "details": {
        "error": "java.sql.SQLException: Connection refused"
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11

上面的响应表示数据库连接失败，导致应用程序的健康状况为 DOWN。

除了默认的健康状况端点之外，Spring Boot Actuator 还提供了其他一些健康状况端点，例如 /actuator/health/liveness 和 /actuator/health/readiness。这些端点可以用于检查应用程序的生命状态和准备状态，以便更好地处理应用程序的故障和问题。

信息端点

信息端点（info endpoint）用于获取应用程序的版本信息，以及其他自定义信息。默认情况下，信息端点返回一个 JSON 响应，其中包含应用程序的版本号和其他信息。

为了访问信息端点，我们可以使用以下 URL：

http://localhost:8080/actuator/info
1

在默认情况下，信息端点返回的 JSON 响应如下所示：

{
  "app": {
    "name": "My Application",
    "version": "1.0.0"
  },
  "java": {
    "version": "11.0.11",
    "vendor": "Oracle Corporation",
    "vmName": "OpenJDK 64-Bit Server VM",
    "vmVersion": "11.0.11+9-LTS",
    "uptime": "3 minutes",
    "startTime": "2023-05-24T08:00:00.000+0000"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

其中 app 对象包含应用程序的名称和版本号，java 对象包含 Java 运行时环境的信息。除了默认的信息端点之外，我们还可以通过自定义属性来添加其他信息，以便更好地了解应用程序的状态和性能。

度量指标端点

度量指标端点（metrics endpoint）用于获取应用程序的度量指标信息，例如 CPU 使用率、内存使用率、请求次数等。Spring Boot Actuator 提供了多个度量指标端点，例如 /actuator/metrics/system.cpu.usage 和 /actuator/metrics/jvm.memory.used。您还可以自定义度量指标，以便更好地了解应用程序的性能和状态。

为了访问度量指标端点，我们可以使用以下 URL：

http://localhost:8080/actuator/metrics
1

在默认情况下，度量指标端点返回一个 JSON 响应，其中包含应用程序的度量指标信息。例如：

{
  "names": [
    "jvm.memory.max",
    "jvm.memory.committed",
    "jvm.memory.used",
    "jvm.buffer.memory.used",
    "jvm.buffer.total.capacity",
    "jvm.buffer.count",
    "logback.events",
    "process.start.time",
    "process.uptime",
    "system.cpu.count",
    "system.cpu.usage",
    "tomcat.sessions.active.current",
    "tomcat.sessions.active.max",
    "tomcat.sessions.alive.max",
    "tomcat.sessions.created",
    "tomcat.sessions.expired",
    "tomcat.sessions.rejected"
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

上面的响应包含了应用程序的度量指标信息列表。我们可以根据需要选择特定的度量指标进行监控和分析。

日志端点

日志端点（loggers endpoint）用于获取应用程序的日志信息。它可以告诉我们应用程序的日志级别、日志输出位置等信息。默认情况下，日志端点返回一个 JSON 响应，其中包含应用程序的日志信息。

为了访问日志端点，我们可以使用以下 URL：

http://localhost:8080/actuator/loggers
1

在默认情况下，日志端点返回的 JSON 响应如下所示：

{
  "levels": [
    "OFF",
    "ERROR",
    "WARN",
    "INFO",
    "DEBUG",
    "TRACE"
  ],
  "loggers": {
    "com.example": {
      "configuredLevel": "DEBUG",
      "effectiveLevel": "DEBUG"
    },
    "org.springframework": {
      "configuredLevel": "INFO",
      "effectiveLevel": "INFO"
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

上面的响应包含了应用程序的日志级别和日志器的配置信息。我们可以根据需要修改特定的日志级别或日志输出位置，以便更好地记录和分析应用程序的日志信息。

关闭应用程序端点

关闭应用程序端点（shutdown endpoint）用于关闭应用程序。默认情况下，关闭应用程序端点是禁用的，我们需要手动启用它才能使用。为了启用关闭应用程序端点，我们需要在配置文件中添加以下配置：

management:
  endpoint:
    shutdown:
      enabled: true
1
2
3
4

启用关闭应用程序端点后，我们可以使用以下 URL 来关闭应用程序：

POST http://localhost:8080/actuator/shutdown
1

使用这个端点需要注意，因为它会直接关闭应用程序，可能会导致数据丢失或其他问题。所以在生产环境中，我们应该对这个端点进行限制或保护，以防止误操作或攻击。

Actuator 的扩展和自定义

除了默认的 Actuator 端点之外，我们还可以扩展和自定义 Actuator 端点，以满足特定的需求。Spring Boot Actuator 提供了多个扩展点和接口，可以让我们方便地扩展和自定义 Actuator 端点。

自定义端点

要自定义一个 Actuator 端点，我们需要实现 Endpoint 接口，并注册到 Spring 容器中。下面是一个自定义的 Actuator 端点的示例：

@Component
public class MyEndpoint implements Endpoint<Map<String, Object>> {

    @Override
    public String getId() {
        return "myendpoint";
    }

    @Override
    public boolean isEnabled() {
        return true;
    }

    @Override
    public boolean isSensitive() {
        return true;
    }

    @Override
    public Map<String, Object> invoke() {
        Map<String, Object> result = new HashMap<>();
        // do something
        return result;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

在上面的代码中，我们实现了 Endpoint 接口，并重写了其中的方法。getId() 方法返回端点的 ID，isEnabled() 方法返回端点是否启用，isSensitive() 方法返回端点是否敏感，invoke() 方法执行端点的逻辑，并返回结果。

在实现了自定义端点后，我们需要将其注册到 Spring 容器中，以便 Actuator 可以发现它并暴露出来。可以使用 @Component 注解将自定义端点注册到 Spring 容器中，例如：

@Component
public class MyEndpoint implements Endpoint<Map<String, Object>> {

    // ...

}
1
2
3
4
5
6

在注册了自定义端点后，我们可以通过以下 URL 来访问它：

http://localhost:8080/actuator/myendpoint
1

自定义健康状况指示器

要自定义健康状况指示器，我们需要实现 HealthIndicator 接口，并注册到 Spring 容器中。下面是一个自定义的健康状况指示器的示例：

@Component
public class MyHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        // do something
        return Health.up().build();
    }
}
1
2
3
4
5
6
7
8
9

在上面的代码中，我们实现了 HealthIndicator 接口，并重写了其中的方法。health() 方法实现了健康状况指示器的逻辑，并返回 Health 对象，表示应用程序的健康状况。在这个例子中，我们返回了一个健康状况为 UP 的 Health 对象。

在实现了自定义健康状况指示器后，我们需要将其注册到 Spring 容器中，以便 Actuator 可以发现它并使用它来计算应用程序的健康状况。可以使用 @Component 注解将自定义健康状况指示器注册到 Spring 容器中，例如：

@Component
public class MyHealthIndicator implements HealthIndicator {

    // ...

}
1
2
3
4
5
6

自定义信息贡献器

要自定义信息贡献器，我们需要实现 InfoContributor 接口，并注册到 Spring 容器中。下面是一个自定义的信息贡献器的示例：

@Component
public class MyInfoContributor implements InfoContributor {

    @Override
    public void contribute(Info.Builder builder) {
        // do something
        builder.withDetail("myinfo", "myvalue");
    }
}
1
2
3
4
5
6
7
8
9

在上面的代码中，我们实现了 InfoContributor 接口，并重写了其中的方法。contribute() 方法实现了信息贡献器的逻辑，并将自定义的信息添加到 Info.Builder 对象中。在这个例子中，我们添加了一个 key 为 “myinfo”，value 为 “myvalue” 的信息。

在实现了自定义信息贡献器后，我们需要将其注册到 Spring 容器中，以便 Actuator 可以发现它并使用它来生成应用程序的信息。可以使用 @Component 注解将自定义信息贡献器注册到 Spring 容器中，例如：

@Component
public class MyInfoContributor implements InfoContributor {

    // ...

}
1
2
3
4
5
6

结论

Spring Boot Actuator 是 Spring Boot 的一个重要特性，它提供了丰富的端点，可以用于监控和管理应用程序。在本文中，我们介绍了 Actuator 的基本使用方法，包括端点的配置、使用、安全性和扩展。希望本文可以帮助读者更好地使用 Spring Boot Actuator 监控和管理应用程序。