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：

org.springframework.bootspring-boot-starter-actuator

对于 Gradle：

dependencies {compile("org.springframework.boot:spring-boot-starter-actuator")
}

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

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

二、spring-boot-actuator 初体验

1、项目中添加 Maven 依赖

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

        org.springframework.bootspring-boot-starter-actuator

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

# 可以看到项目成功关闭

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 可以看到：

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

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

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

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

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

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

{"configuredLevel": "DEBUG"
}

修改：

修改后：

六、beans 端点

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

七、关于自定义 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请求