SpringBoot：模块探究之spring-boot-actuator

spring-boot-actuator 模块 是 spring-boot 用来查询或监控项目中各种组件、维度的度量指标（如：环境变量信息、日志级别、SpringBean 信息、组件（Redis、Mq、DB）健康状态）时使所用的模块。 此外 spring-boot-actuator 模块 还会向外提供系统运行的情况（如程序是否存活、Jvm 状态）等相关信息。 我们可以通过使用 Http 或 Jmx 的方式来使用 spring-boot-actuator。 ～ 本篇内容包括：spring-boot-actuator 模块介绍、spring-boot-actuator 初体验、health 端点、metrics 端点、loggers 端点、beans 端点、关于自定义 Endpoint

文章目录

• 一、spring-boot-actuator 模块介绍
  • 1、关于 spring-boot-actuator 模块
  • 2、spring-boot-actuator 源码地址
  • 3、启用 spring-boot-actuator 模块

• 二、spring-boot-actuator 初体验
  • 1、项目中添加 Maven 依赖
  • 2、启动项目访问 Api
  • 3、添加 actuator 配置
  • 4、启动项目访问 Api
  • 5、spring-boot-actuator 内置端点
• 三、health 端点
• 四、metrics 端点
  • 1、/metrics 端点
  • 2、/metrics/{name} 端点
  • 3、/metrics 自定义端点
• 五、loggers 端点
  • 1、/loggers 端点查看运行时日志等级
  • 2、/loggers/{name} 端点查看运行时日志等级
  • 3、/loggers 端点改变运行时日志等级
• 六、beans 端点
• 七、关于自定义 Endpoint

一、spring-boot-actuator 模块介绍

1、关于 spring-boot-actuator 模块

spring-boot-actuator 模块 是 spring-boot 用来查询或监控项目中各种组件、维度的度量指标（如：环境变量信息、日志级别、SpringBean 信息、组件（Redis、Mq、DB）健康状态）时使所用的模块。

此外 spring-boot-actuator 模块 还会向外提供系统运行的情况（如程序是否存活、Jvm 状态）等相关信息。

我们可以通过使用 Http 或 Jmx 的方式来使用 spring-boot-actuator。

2、spring-boot-actuator 源码地址

spring-boot-actuator 位于 spring-boot 项目中。

spring-boot-actuator 在 源码地址为： https://github.com/spring-projects/spring-boot/tree/v2.1.0.RELEASE/spring-boot-project/spring-boot-actuator

3、启用 spring-boot-actuator 模块

对于 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")
}

亦或使用 SpringBoot CLI，可以使用如下 @Grab 注解：

@Grab('spring-boot-starter-actuator')

二、spring-boot-actuator 初体验

1、项目中添加 Maven 依赖

# 在 pom 文件中添加以下内容

        <!--   对应用系统的自省和监控     -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>

2、启动项目访问 Api

启动项目访问 /actuator/health 地址，得到以下级过

{"status":"UP"}

其中 /actuator 是访问 endpoints 的默认 url 前缀，/health 则展示应用的健康信息。

可以通过以下属性配置，修改 endpoints 的 url 前缀：

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

修改之后 health 访问地址为 /simple/health。

3、添加 actuator 配置

actuator 的 health 端点是默认开启的，下面我们将尝试关闭所有默认配置，并启用和使用 shutdown 端点（默认不启用），优雅的关闭程序

# Yaml 配置文件中添加以下内容

#启用端点
management:
  #全局配置
  endpoints:
    #关闭默认配置(即全部内容需重新配置)
    enabled-by-default: false
    #http方式暴露
    web:
      #actuator提供的api接口根路径
      base-path: "/simple"
      exposure:
        #需要开放的端点，默认只打开health、info，*表示所有
        include: "*"
        #需要排除的端点
        exclude:
  #单一端点配置
  endpoint:
    shutdown:
      #启用shutdown端点
      enabled: true

4、启动项目访问 Api

# 修改配置后，Post 访问端点 /simple/shutdown

image-20221212171147107

# 可以看到项目成功关闭

image-20221212171254571

5、spring-boot-actuator 内置端点

Actuator 提供 13 个端点，可以分为三大类：配置端点、度量端点和其他端点。具体如下表所示

三、health 端点

当我们开启 health 的健康端点时，我们能够查到应用健康信息是一个汇总的信息，访问 /health 时，我们获取到的信息是 {“status”:“UP”}，status 的值还有可能是 DOWN。

# 要想查看详细的应用健康信息需要加入以下配置：

#单一端点配置  
endpoint:
    health:
      show-details: always

该属性可以使用以下值之一进行配置：

1. never：默认配置，不展示详细信息，只展示 up/down 状态，
2. when-authorized：详细信息将会展示给通过认证的用户。授权的角色可以通过 management.endpoint.health.roles 配置
3. always：对所有用户暴露详细信息

# 添加后可以得到以下信息：

{
    "status": "UP",
    "components": {
        "redis": {
            "status": "UP",
            "details": {
                "version": "3.2.11"
            }
        },
        "db": {
            "status": "UP",
            "details": {
                "database": "MySQL",
                "validationQuery": "isValid()"
            }
        },
        "diskSpace": {
            "status": "UP",
            "details": {
                "total": 499963174912,
                "free": 281442709504,
                "threshold": 10485760,
                "exists": true
            }
        },
        "ping": {
            "status": "UP"
        }
    }
}

从上面的应用的详细健康信息发现，健康信息包含磁盘空间、redis、DB，启用监控的这个 SpringBoot 应用确实是连接了 Redis 和 MySQL 数据库，Actuator 就自动给监控起来了，确实是很方便、很有用。

Ps：diskSpace 是指磁盘空间监测！

/health 端点有很多自动配置的健康指示器：如 Redis、Rabbitmq、db 等组件。当你的项目有依赖对应组件的时候，这些健康指示器就会被自动装配，继而采集对应的信息。

四、metrics 端点

1、/metrics 端点

# /metrics 端点用来查看所有可追踪的度量，比如我当前项目访问 /metrics 端点：

{
    "names": [
        "application.ready.time",
        "application.started.time",
        "disk.free",
        "disk.total",
        "executor.active",
				...
    ]
}

Actuator 在这个界面看不到具体的指标信息，只是展示了一个指标列表。为了获取到某个指标的详细信息，我们可以请求具体的指标信息，即 /metrics/{name} 端点

2、/metrics/{name} 端点

/metrics 各个指标说明如下：

3、/metrics 自定义端点

metrics 端点除了默认的这些统计指标外，我们还可以实现自定义统计指标。Metrics 提供 4 种基本的度量类型：Gauge、Counter、Timer、Summary

• Cauge 是表示单个的变化的值，例如温度，气压。与 Counter 的区别在于，Gauge 的值不总是增加的；Gauge 对象一旦被创建，就不能手动对其中的值进行修改。在每次取样时，Gauge 会返回当前值；
• Counter 只允许增加值，Counter 所表示的计数值是 double 类型，默认情况下增加的值是 1.0；
• Timer 通常用来记录事件的持续时间。Timer 会记录两类的数据，事件的数量和总的持续时间。Timer 提供了不同方式来记录持续时间。第一种方式是使用 record() 方法来记录 Runnable 和 Callable 对象的运行时间，第二种方式是使用 Timer.Sample 来保存计时状态；
• Summary 用来记录指标的分布，Summary 根据每个指标的值，把值分配到对应的 bucket 中。Micrometer 默认的 bucket 的值从 1 到 Long.MAX_VALUE，可以通过 minimumExpectedValue 和 maximumExpectedValue 来控制 bucket 的范围，如果指标的值较小，还可以通过 scale 来设置一个值对数值进行放大。

五、loggers 端点

1、/loggers 端点查看运行时日志等级

loggers 端点暴露了我们程序内部配置的所有 logger 的信息。我们访问 /loggers 可以看到：

image-20221213110600372

2、/loggers/{name} 端点查看运行时日志等级

你也可以通过下述方式访问单独一个 logger：

http://localhost:8080/actuator/loggers/{name}

image-20221213110745258

3、/loggers 端点改变运行时日志等级

loggers 端点能够动态修改日志等级。

比如，我们可以通过以下几种方式来修改 root logger 的日志等级。我们只需要发起一个 URL 为 http://localhost:8080/actuator/loggers/root 的 POST 请求，POST 报文如下：

{
   "configuredLevel": "DEBUG"
}

修改：

image-20221213111000537

修改后：

image-20221213111024077

六、beans 端点

beans 端点会返回 Spring 容器中所有 bean 的别名、类型、是否单例、依赖等信息。

image-20221213111414635

七、关于自定义 Endpoint

默认的端点虽然可以满足大多数的需求，但一些特殊的需求还是需要能够支持自定义端点的。

自定义 Endpoint 端点，只需要在我们的新建 Bean 上使用 @Endpoint 注解即可， Bean 中的方法就可以通过 JMX 或者 HTTP 公开。

除此之外，还可以使用 @JmxEndpoint 或 @WebEndpoint 编写 EndPoint。但这些 EndPoint 仅限于各自的公开方式。例如，@WebEndpoint 仅通过 HTTP 公开，而不通过 JMX 公开。

那么是不是类中所有的方法都支持对外公开呢？

很明显不是的。Actuator 提供了三个用于方法上的注解，只有加三个注解的方法才支持对外公开，并且每个注解都有支持它的 HTTP method。

• @ReadOperation 对应 HTTP 的 GET请求
• @WriteOperation 对应 HTTP 的 POST请求
• @DeleteOperation 对应 HTTP 的 DELETE请求