2025年Springboot中使用Actuator监控项目

大家好，我是讯享网，很高兴认识大家。

一、Actuator介绍

二、Actuator监控应用

1、引入Actuator

Spring Boot Actuator提供了应用的审计 (Auditing)、健康(Health)状态信息、数据采集(Metrics gathering)统计等监控运维的功能。

同时，还提供了可扩展的端点(Endpoint)功能，方便使用者进行自定义监控指标。默认情况下，这些信息以jSON的数据格式呈现，用户也可以使用Spring BootAdmin项目进行界面管理
Actuator 是 Spring Boot 提供的对应用系统的自省和监控的集成功能，可以查看应用配置的详细信息，例如自动化配置信息、创建的 Springbeans 以及一些环境属性等。
为了保证 atuator 暴露的监控接口的安全性，需要添加安全控制的依赖 spring-boot-start-securty依赖，访问应用监控端点时，都需要输入验证信息。Security 依赖，可以选择不加，不进行安全管理，但不建议这么做。

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

讯享网

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

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

可以在官网中查看

Production-ready Features (spring.io)

Actuator 提供了十几个接口，具体如下表所示

/actuator/health：获取应用程序的健康状态信息。应用程序可以通过实现HealthIndicator接口来自定义健康检查逻辑。
/actuator/info：获取应用程序的自定义信息。应用程序可以通过实现InfoContributor接口来向/info端点添加额外的信息。
/actuator/metrics：获取应用程序的度量指标信息。应用程序可以通过实现MeterBinder接口来向/metrics端点添加自定义度量指标。
/actuator/trace：获取应用程序的HTTP请求跟踪信息。
/actuator/beans：获取应用程序中所有的Spring Bean信息。
/actuator/mappings：获取应用程序中所有的请求映射信息。
/actuator/env：获取应用程序的环境变量和配置属性信息。
/actuator/loggers：获取应用程序的日志配置信息。
/actuator/threaddump：获取应用程序的线程信息。
/actuator/scheduledtasks：获取应用程序中所有的定时任务信息。
/actuator/httptrace：获取应用程序的HTTP请求跟踪信息（包括请求和响应的详细信息）。
/actuator/sessions：获取应用程序的会话信息（仅适用于基于Spring Session的应用程序）。

2、暴露端点

默认端点是无法访问的，我么需要配置开启

讯享网

如下

讯享网management: endpoints: web: exposure: include: "*" jmx: exposure: include: "*"

访问http://localhost/actuator接口查看暴露出来的端点

3、路径映射

默认情况下所有端点都暴露在“/actuator”路径下，也可以改/actuator的路徑，可以定成自己想要的：

#原本內建的/actuator/xxx改成/manage/xxx，可以用來防止被其他人猜到 management.endpoints.web.base-path=/manage #同时可以将health修改成healthcheck management.endpoints.web.path-mapping.health=healthcheck

4、管理端口调整

讯享网#指定端口，默认跟server.port一样，可以防止被其他人猜到 management.server.port=10111

5、端点响应缓存

对于一些不带参数的端点请求会自动进行缓存，我们可以通过如下方式配置缓存时间，下面配置表示 beans 端点的缓存时间为 100s

management.endpoint.beans.cache.time-to-live=100s

三、端点参数详解

1、/health 端点

/health配置

要想查看详细的应用健康信息需要配置：

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

按照上述配置，配置成always之后，我们启动项目再次访问
http://127.0.0.1:10111/actuator/health，获取的信息如下

讯享网{ "status": "UP", "details": { "diskSpace": { "status": "UP", "details": { "total": 8, "free": 0, "threshold":  } }, "redis": { "status": "UP", "details": { "version": "3.2.11" } }, "db": { "status": "UP", "details": { "database": "Oracle", "hello": "Hello" } } } }

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

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

如上面的 diskSpace 节点信息就是DiskSpaceHealthIndicator 在起作用。

上述截图取自官方文档。

当如上的组件有一个状态异常，应用服务的整体状态即为down。我们也可以通过配置禁用某个组件的健康监测。

management.health.defaults.enabled: false

/health原理

默认情况下，最终的spring boot应用的状态是由HealthAggregator汇总而成的，汇总的算法是：

设置状态码顺序：setStatusOrder(Status.DOWN, Status.OUT_OF_SERVICE, Status.UP, Status.UNKNOWN)。
过滤掉不能识别的状态码。
如果无任何状态码，整个spring boot应用的状态是 UNKNOWN。
将所有收集到的状态码按照 1 中的顺序排序。
返回有序状态码序列中的第一个状态码，作为整个spring boot应用的状态。

源代码请参见：
org.springframework.boot.actuate.health.OrderedHealthAggregator。

Spring boot框架自带的 HealthIndicators 目前包括：

你可以通过
management.health.defaults.enabled这个配置项将它们全部禁用掉，也可以通过
management.health.xxxx.enabled将其中任意一个禁用掉。

自定义 HealthIndicator

你需要实现其中的health()方法，并返回自定义的健康状态响应信息，该响应信息应该包括一个状态码和要展示详细信息。

例如，下面就是一个接口HealthIndicator的实现类：

import org.springframework.boot.actuate.health.Health; import org.springframework.boot.actuate.health.HealthIndicator; import org.springframework.stereotype.Component; @Component public class MyHealthIndicator 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(); } }

另外，除了Spring boot定义的几个状态类型，我们也可以自定义状态类型，用来表示一个新的系统状态。

例如，在你自定义的健康检查HealthIndicator的实现类中，使用了自定义的状态类型FATAL，为了配置该状态类型的严重程度，你需要在application的配置文件中添加如下配置：

同样，你也需要为自定义的状态类型设置对应的HTTP状态码，例如，下面的配置可以将 FATAL 映射为 503（服务不可用）：

下面是内置健康状态类型对应的HTTP状态码列表：

2、/metrics 端点

查看所有可追踪的度量

/metrics端点用来返回当前应用的各类重要度量指标，比如：内存信息、线程信息、垃圾回收信息、tomcat、数据库连接池等。

讯享网{ "names": [ "hikaricp.connections", "hikaricp.connections.acquire", "hikaricp.connections.active", "hikaricp.connections.creation", "hikaricp.connections.idle", "hikaricp.connections.max", "hikaricp.connections.min", "hikaricp.connections.pending", "hikaricp.connections.timeout", "hikaricp.connections.usage", "jvm.buffer.count", "jvm.buffer.memory.used", "jvm.buffer.total.capacity", "jvm.classes.loaded", "jvm.classes.unloaded", "jvm.gc.live.data.size", "jvm.gc.max.data.size", "jvm.gc.memory.allocated", "jvm.gc.memory.promoted", "jvm.gc.pause", "jvm.memory.committed", "jvm.memory.max", "jvm.memory.used", "jvm.threads.daemon", "jvm.threads.live", "jvm.threads.peak", "jvm.threads.states", "logback.events", "process.cpu.usage", "process.start.time", "process.uptime", "system.cpu.count", "system.cpu.usage", "tomcat.cache.access", "tomcat.cache.hit", "tomcat.global.error", "tomcat.global.received", "tomcat.global.request", "tomcat.global.request.max", "tomcat.global.sent", "tomcat.servlet.error", "tomcat.servlet.request", "tomcat.servlet.request.max", "tomcat.sessions.active.current", "tomcat.sessions.active.max", "tomcat.sessions.alive.max", "tomcat.sessions.created", "tomcat.sessions.expired", "tomcat.sessions.rejected", "tomcat.threads.busy", "tomcat.threads.config.max", "tomcat.threads.current", "zipkin.reporter.messages", "zipkin.reporter.messages.total", "zipkin.reporter.queue.bytes", "zipkin.reporter.queue.spans", "zipkin.reporter.spans", "zipkin.reporter.spans.dropped", "zipkin.reporter.spans.total" ] }

各个指标说明如下：

查看某个度量的详细信息

不同于1.x，Actuator在这个界面看不到具体的指标信息，只是展示了一个指标列表。为了获取到某个指标的详细信息，我们可以请求具体的指标信息，像这样：

http://localhost:8080/actuator/metrics/{MetricName}
比如我访问
/actuator/metrics/jvm.memory.max，返回信息如下：

添加自定义统计指标

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

1，Gauge（计量器）

Gauge（计量器）是最简单的度量类型，只有一个简单的返回值，他用来记录一些对象或者事物的瞬时值。

（1）假设我们在一个 Contoller 使用一个类型为 Gauge 的计数器来记录一个数值：

@RestController public class HelloController { @GetMapping("/hello") public void hello() { Metrics.gauge("user.test.gauge", 3); } }

（2）通过 /actuator/metrics 接口可以看到我们自定义的这个指标：

2，Counter（计数器）

Counter（计数器）简单理解就是一种只增不减的计数器。它通常用于记录服务的请求数量、完成的任务数量、错误的发生数量等等。

（1）为方便使用首先我们自定义一个计数器服务：

讯享网@Service public class MyCounterService { static final Counter userCounter = Metrics.counter("user.counter.total", "services", "demo"); public void processCollectResult() { userCounter.increment(1D); } }

（2）然后增加一个 controller，触发这个服务：

@RestController public class HelloController { @Autowired MyCounterService myCounterService; @GetMapping("/hello") public void hello() { myCounterService.processCollectResult(); } }

（3）通过 /actuator/metrics 接口可以看到我们自定义的这个指标：

3，Timer（计时器）

Timer（计时器）可以同时测量一个特定的代码逻辑块的调用（执行）速度和它的时间分布。

简单来说，就是在调用结束的时间点记录整个调用块执行的总时间，适用于测量短时间执行的事件的耗时分布，例如消息队列消息的消费速率。

（1）假设我们在一个 Contoller 使用 Timer 来记录某个方法的执行时长：

讯享网@RestController public class HelloController { private Timer timer = Metrics.timer("user.test.timer","timer", "timersample"); @GetMapping("/hello") public void hello() { // 执行createOrder方法并记录执行时间 timer.record(() -> createOrder()); } //模拟方法耗时 private void createOrder() { try { TimeUnit.SECONDS.sleep(3); } catch (InterruptedException e) { } } }

4，Summary（摘要）

Summary（摘要）用于跟踪事件的分布。它类似于一个计时器，但更一般的情况是，它的大小并不一定是一段时间的测量值。

在 micrometer 中，对应的类是 DistributionSummary，它的用法有点像 Timer，但是记录的值是需要直接指定，而不是通过测量一个任务的执行时间。

@RestController public class HelloController { private DistributionSummary summary = Metrics.summary("user.test.summary","summary", "summarysample"); @GetMapping("/hello") public void hello() { summary.record(2D); summary.record(3D); summary.record(4D); } }

3、/loggers 端点

查看日志等级

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

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

讯享网http://localhost:8080/actuator/loggers/{name}

 { "configuredLevel": "INFO", "effectiveLevel": "INFO" }

改变运行时日志等级

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

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

讯享网{ "configuredLevel": "DEBUG" }

1、使用工具修改：

2、使用浏览器修改：

先在chrome浏览器中，按F12打开console(控制台）；然后执行以下脚本（url参数根据自己需求进行修改），回车执行。

fetch(new Request('http://localhost:8080/masl/actuator/loggers/ROOT',{ method:'POST', headers: {'Content-Type': 'application/json;charset=UTF-8'}, body:"{\"configuredLevel\": \"DEBUG\"}" })).then((resp)=>{console.log(resp)})

3、使用shell脚本修改：

讯享网curl -X "POST" "http://localhost:8080/masl/actuator/loggers/ROOT" -H "Content-Type: application/json;charset=UTF-8" -d '{"configuredLevel": "DEBUG"}'

仔细想想，这个功能是不是非常有用。还可以只修改某个类的日志级别（把上面的ROOT替换成类的全路径，如：
com.zat.asl.MaslApplication）

如果在生产环境中，你想要你的应用输出一些Debug信息以便于你诊断一些异常情况，你只需要按照上述方式就可以修改，而不需要重启应用。

4、/info 端点

/info端点可以用来展示应用信息，主要包含三大类：自定义信息、Git 信息、以及项目构建信息。下面主要介绍自定义信息。

info.app.name=actuator-test-demo info.app.encoding=UTF-8 info.app.java.source=1.8 info.app.java.target=1.8

讯享网{ "app": { "encoding": "UTF-8", "java": { "source": "1.8.0_131", "target": "1.8.0_131" }, "name": "actuator-test-demo" } }

（2）我们也可以通过 Java 代码自定义信息，只需要将自定义类继承自 InfoContributor，然后实现该类中的 contribute 方法即可：

@Component public class MyInfo implements InfoContributor { @Override public void contribute(Info.Builder builder) { Map<String, String> info = new HashMap<>(); info.put("name", "航歌"); info.put("email", ""); builder.withDetail("author", info); } }

5、/beans 端点

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

6、/heapdump 端点

7、/threaddump 端点

这个端点我个人觉得特别有用，方便我们在日常定位问题的时候查看线程的情况。主要展示了线程名、线程ID、线程的状态、是否等待锁资源、线程堆栈等信息。就是可能查看起来不太直观。

访问
http://localhost:8080/actuator/threaddump返回如下：

这个端点属于操作控制类端点，可以优雅关闭 Spring Boot 应用。要使用这个功能首先需要在配置文件中开启：

curl -X "POST" "http://localhost:8080/actuator/shutdown"
返回信息：

讯享网{ "message": "Shutting down, bye..." }

然后应用程序被关闭。类似停服的操作还有很多，比如restart、pause等。可根据具体版本进行配置。

由于开放关闭应用的操作本身是一件非常危险的事，所以真正在线上使用的时候，我们需要对其加入一定的保护机制，

比如：定制Actuator的端点路径、整合Spring Security进行安全校验等。（不是特别必要的话，这个端点不用开）。

定制Actuator的端点路径和端口：

management.endpoints.web.base-path 自定义shutdown的请求路径；
management.server.address 设置为本地ip，防止远程访问该连接进行关闭服务；
management.server.port 自定义shutdown请求路径的端口号；

调整后的配置文件如下：

management: endpoint: shutdown: enabled: true endpoints: web: exposure: include: '*' jmx: exposure: include: '*' server: # 自定义端口 port: 8888 # 不允许远程管理连接，安全性考虑 address: 127.0.0.1

四、自定义端点

默认的端点虽然可以满足大多数的需求，但一些特殊的需求还是需要能够支持自定义端点的。自定义 Endpoint 端点，只需要在我们的新建Bean上使用注解即可

Spring Boot2x 开始，Actuator支持CRUD模型，而不是旧的RW(读/写)模型

@Endpoint 同时支]MX和http
@JmxEndpoint 只支持]MX技术
@WebEndpoint 只支持http

通过在一个端点类(必须是Spring Bean)上添加上面其中一个来表明该类是一个端点类。在类的方法使用@ReadOperation，@WriteOperation或@DeleteOperation，这分别会映射到Http中的GET、POST、DELETE(对http来说）

讯享网@Component @Endpoint(id = "my") id就是访问路径 public class EndpointCustom { @ReadOperation public String endpointCustomRead(String content) { return "请求的内容: " + content; } @WriteOperation public String endpointCustomWrite(String content) { return "写的内容: " + content; } @DeleteOperation public String endpointCustomDelete(String content) { return "删除的内容: " + content; } }

对应GET请求：

同样的POST请求为：